diff --git a/README.md b/README.md index 02a84f3..be47f08 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,14 @@ The main PCSX2 website is a statically generated website, leveraging [Docusaurus](https://docusaurus.io/docs). -- [Setup](#setup) - - [Windows](#windows) - - [Linux](#linux) -- [Developing](#developing) - - [Making a new Article](#making-a-new-article) - - [Caveats if Migrating a Legacy Article](#caveats-if-migrating-a-legacy-article) - - [Builtin Component Documentation](#builtin-component-documentation) +- [PCSX2 Website](#pcsx2-website) + - [Setup](#setup) + - [Windows](#windows) + - [Linux](#linux) + - [Developing](#developing) + - [Making a new Article](#making-a-new-article) + - [Caveats if Migrating a Legacy Article](#caveats-if-migrating-a-legacy-article) + - [Builtin Component Documentation](#builtin-component-documentation) ## Setup @@ -23,9 +24,7 @@ scoop install git nodejs npm install --global yarn ``` -Navigate to your local git repository for the site and use the below to start the server. - -To start the server you will need to be in your Github repository that contains the `package.json`. +To start the server you will need to be in your Github repository that contains the `package.json`. Use this command to start the server: ```bash yarn start # alternatively, you can use `npm run start` @@ -35,7 +34,39 @@ Browse to http://localhost:8080/ ### Linux -TODO - but very similar just using your package manager of choice +You need to install NodeJS using your package manager, here are a few examples: + +Ubuntu: + +```sh +sudo apt-get install nodejs +``` + +Fedora: + +```sh +sudo dnf install nodejs +``` + +Arch Linux: + +```sh +sudo pacman -Syu nodejs +``` + +Now you can install `yarn` via NPM (Make sure you have installed NodeJS first): + +```sh +npm install --global yarn +``` + +To start the server you will need to be in your Github repository that contains the `package.json`. Use this command to start the server: + +```bash +yarn start # alternatively, you can use `npm run start` +``` + +Browse to http://localhost:8080/ ## Developing diff --git a/docs/advanced/building.md b/docs/advanced/building.md new file mode 100644 index 0000000..e202c94 --- /dev/null +++ b/docs/advanced/building.md @@ -0,0 +1,217 @@ +--- +title: "Building PCSX2" +summary: "How to build PCSX2 locally" +draft: false +toc: true +sidebar_position: 1 +--- + +This section will show you how you can build PCSX2 locally on your machine. + +## Building on Windows + +### Required Dependencies for Qt + +If you are developing against the `pcsx2-qt` solution, you will need to do the following: + +- Download the binaries [from here](https://github.com/PCSX2/pcsx2-windows-dependencies/releases/) + - tools / symbols are not required +- Extract into the main folder (where the `PCSX2_qt.sln` file is); you should see a new `deps` folder after extraction +- Ensure you have opened the `*-qt` .sln file. + +### Required Build Applications + + + +- [Visual Studio Community](https://www.visualstudio.com/downloads/) + - Installing just the "Desktop development with C++" workload should be enough, otherwise select individually: + - C++ ATL for v142 build tools (x86 & x64) + - MSVC v142 - VS 2019 C++ x64/x86 build tools + - Windows 10 SDK +- [Git for Windows](https://git-scm.com/download/win) + +### Other Requirements + +Widescreen and No-Interlacing cheats are sourced from [a separate repository](https://github.com/PCSX2/pcsx2_patches). You might consider putting them in your working directory to ensure your development environment matches shipping builds: + +- Download both `.zip` files from here: https://github.com/PCSX2/pcsx2_patches/releases/ +- Put them (without extracting) in `bin/resources`. + +## Building On Linux + +This guide demonstrates how to build PCSX2 in Linux environments. Note that the steps provided below may vary depending on the distribution - such variances are not officially supported by the PCSX2 team. + +Note that the procedure defined herein closely mirrors the scripts used by the PCSX2 CI process. These scripts provide more information behind the build process than what is stated here. + +- https://github.com/PCSX2/pcsx2/blob/master/.github/workflows/linux_build_qt.yml +- https://github.com/PCSX2/pcsx2/tree/master/.github/workflows/scripts/linux + +### Dependencies + +Note that dependencies tend to change over time, along with their required versions. In particular, PCSX2 no longer supports the gcc compiler, as it has transitioned to clang/llvm due to the many benefits the latter compiler offers, including superior efficiency and speed. + +#### Ubuntu Package List + +```sh +build-essential clang cmake curl extra-cmake-modules git libasound2-dev libaio-dev libavcodec-dev libavformat-dev libavutil-dev libcurl4-openssl-dev libdbus-1-dev libdecor-0-dev libegl-dev libevdev-dev libfontconfig-dev libfreetype-dev libgtk-3-dev libgudev-1.0-dev libharfbuzz-dev libinput-dev libopengl-dev libpcap-dev libpipewire-0.3-dev libpulse-dev libssl-dev libswresample-dev libswscale-dev libudev-dev libwayland-dev libx11-dev libx11-xcb-dev libxcb1-dev libxcb-composite0-dev libxcb-cursor-dev libxcb-damage0-dev libxcb-glx0-dev libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev libxcb-present-dev libxcb-randr0-dev libxcb-render0-dev libxcb-render-util0-dev libxcb-shape0-dev libxcb-shm0-dev libxcb-sync-dev libxcb-util-dev libxcb-xfixes0-dev libxcb-xinput-dev libxcb-xkb-dev libxext-dev libxkbcommon-x11-dev libxrandr-dev lld llvm ninja-build pkg-config zlib1g-dev +``` + +#### Fedora Package List + +The following package list is sufficient for building PCSX2 as of 2024/04/06 with Fedora 39. You must build the third-party dependencies using the script from the CI, as instructed below. + +```sh +alsa-lib-devel brotli-devel clang cmake dbus-devel egl-wayland-devel extra-cmake-modules fontconfig-devel gcc-c++ gtk3-devel libaio-devel libcurl-devel libdecor-devel libevdev-devel libICE-devel libinput-devel libpcap-devel libSM-devel libX11-devel libXau-devel libxcb-devel libXcomposite-devel libXcursor-devel libXext-devel libXfixes-devel libXft-devel libXi-devel libxkbcommon-devel libxkbcommon-x11-devel libXpresent-devel libXrandr-devel libXrender-devel lld llvm make mesa-libEGL-devel mesa-libGL-devel ninja-build openssl-devel patch pcre2-devel perl-Digest-SHA pipewire-devel pulseaudio-libs-devel systemd-devel wayland-devel xcb-util-cursor-devel xcb-util-devel xcb-util-errors-devel xcb-util-image-devel xcb-util-keysyms-devel xcb-util-renderutil-devel xcb-util-wm-devel xcb-util-xrm-devel zlib-devel +``` + +#### NixOS nix-shell + +```nix +{ pkgs ? import { } }: +pkgs.mkShell { + buildInputs = with pkgs; + with qt6; + with xorg; [ + curl + extra-cmake-modules + ffmpeg + libaio + libbacktrace + libpcap + libwebp + libXrandr + lz4 + qtbase + qtsvg + qttools + qtwayland + SDL2 + shaderc + soundtouch + vulkan-headers + wayland + zstd + clang + lld + ]; + + nativeBuildInputs = with pkgs; + with qt6; [ + cmake + pkg-config + strip-nondeterminism + wrapQtAppsHook + zip + ]; + + qtWrapperArgs = let + libs = with pkgs; + lib.makeLibraryPath + ([ vulkan-loader shaderc ] ++ cubeb.passthru.backendLibs); + in [ "--prefix LD_LIBRARY_PATH : ${libs}" ]; + + shellHook = '' + if [ ! -d "$(pwd)/pcsx2" ]; then + echo "pcsx2 not cloned, cloning..." + git clone git@github.com:PCSX2/pcsx2.git + fi + if [ ! -d "$(pwd)/pcsx2/build" ]; then + echo "pcsx2 not configured, configuring..." + cd pcsx2 + cmake -B build -DDISABLE_ADVANCE_SIMD=true -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS_INIT="-fuse-ld=lld" -DCMAKE_MODULE_LINKER_FLAGS_INIT="-fuse-ld" -DCMAKE_SHARED_LINKER_FLAGS_INIT="-fuse-ld=lld" -DCMAKE_PREFIX_PATH="$PWD/deps" -GNinja + cd .. + fi + + + bashdir=$(mktemp -d) + makeWrapper "$(type -p bash)" "$bashdir/bash" "''${qtWrapperArgs[@]}" + export NIX_ENFORCE_PURITY=0 + exec "$bashdir/bash" + ''; +} +``` + +### Build procedure + +#### Clone repository + +```sh +git clone --recursive https://github.com/PCSX2/pcsx2.git +cd pcsx2 +``` + +#### Build Dependencies + +PCSX2 depends on multiple third-party libraries, which should be built for your development environment. We provide a convenience script for building these dependencies, which is also used by our CI runners for release builds. + +This will build the dependencies to your PCSX2 Git tree, in the `deps` directory. You can also specify an alternative location, but be sure to adjust `CMAKE_PREFIX_PATH` in the next step. + +```sh +.github/workflows/scripts/linux/build-dependencies-qt.sh deps +``` + +#### Prepare build with CMake + +```sh +cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS_INIT="-fuse-ld=lld" -DCMAKE_MODULE_LINKER_FLAGS_INIT="-fuse-ld" -DCMAKE_SHARED_LINKER_FLAGS_INIT="-fuse-ld=lld" -DCMAKE_PREFIX_PATH="$PWD/deps" -GNinja +``` + +Note the following optional CMake flags that are commonly used: + +- `-DCMAKE_BUILD_TYPE=Release|Devel|Debug` + + - `Release`: Fastest build, but lacks debug/crash information + - `Devel`: Adds detailed trace logging abilities, but lacks debug/crash information + - `Debug`: Slowest build as there are no compiler optimizations, but offers debug/crash information + +- `-DCMAKE_CXX_COMPILER_LAUNCHER=ccache` + + - Uses ccache to speed up the build process + +- `-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON` + - Turns on link time optimization, which provides a noticeable performance improvement. + +#### Execute build + +```sh +ninja -C build +``` + +#### Running PCSX2 + +PCSX2 can be launched from the build directory: + +```sh +build/bin/pcsx2-qt +``` + +## Building on MacOS + +### Building on an Intel Mac + +Build the dependencies using the CI's build script: `.github/workflows/scripts/macos/build-dependencies.sh deps` (this will build the dependencies into the directory `deps`). If you want to use a package manager, you can look at the install script to see the required dependencies. Note that we patch extra features into `libshaderc`, so you will need to compile that one yourself, as the package manager's version will not work. + +You can set the environment variable `BUILD_FFMPEG=0` to tell the dependency build script to build all the dependencies except ffmpeg, allowing you to use your homebrew or macports-installed ffmpeg, which probably has more features enabled than the build script's. + +Building on an Intel Mac should work similarly to building on Linux. Run cmake with `cmake /path/to/pcsx2/source -DCMAKE_PREFIX_PATH=/path/to/deps -DCMAKE_BUILD_TYPE=Release`, then `make`. The final `.app` will be in `pcsx2-qt/PCSX2.app` in the build directory. (The `CMAKE_PREFIX_PATH` is only needed if you used the CI's build script to install dependencies.) + +Add `-DUSE_LINKED_FFMPEG=ON` for video capture support. + +### Building on an ARM (Apple Silicon) Mac + +:::warning +PCSX2 does not support building for ARM. You will need to make Intel builds even on Apple Silicon and run them in Rosetta. +::: + +You will need Intel versions of all the dependencies. **Dependencies from Homebrew will not work.** The dependency build script will handle this for you (see Intel instructions). If you use MacPorts, install your packages with `+universal`. Note that we don't link to any libraries from `qt6-qttools`, so you can skip the universal on that one (and it links with libclang, so I'd recommend skipping it unless you really want to sit around while MacPorts builds a universal build of clang and llvm). + +Add the following extra flags to the cmake invocation listed in the Intel Mac section: + +- `-DCMAKE_OSX_ARCHITECTURES=x86_64`. This tells cmake to do an Intel build even though you're on an ARM Mac. + +### Building for development + +The following extra cmake flags may be useful when building for working on PCSX2: + +- `-DSKIP_POSTPROCESS_BUNDLE=ON`. This disables a post-build step that fixes up all the dependencies and shoves them into the app bundle for easy distribution. Saves time on incremental builds. +- `-G Xcode`. Tells cmake to generate an Xcode project instead of makefiles. Allows you to use Xcode to work on PCSX2. diff --git a/docs/advanced/debugger.md b/docs/advanced/debugger.md index ea32b19..21de82c 100644 --- a/docs/advanced/debugger.md +++ b/docs/advanced/debugger.md @@ -1,7 +1,7 @@ --- title: "Debugger" description: "Inspect and modify the state of the program running in the virtual machine." -sidebar_position: 1 +sidebar_position: 2 --- You can inspect and modify the state of the program running in the virtual machine using the debugger window. This can be useful for developing patches, fixing bugs, and reverse engineering games. diff --git a/docs/advanced/gsdumprunner.md b/docs/advanced/gsdumprunner.md new file mode 100644 index 0000000..8822fc4 --- /dev/null +++ b/docs/advanced/gsdumprunner.md @@ -0,0 +1,64 @@ +--- +title: "GS Dump Runner" +summary: "How to use the GS Dump Runner" +draft: false +toc: true +sidebar_position: 3 +--- + +The GS dump runner is designed to automatically run and compare a large number of GS dumps and output any differences found with pictures. + +`pcsx2-gsrunner` does not build by default. You need to right click in the solution explorer in VS, and select Build. + +:::info +The GS dump runner is only available for Windows at the moment. +::: + +To use: + +:::tip +You can add `-parallel 4` as a parameter for it to run multiple dumps at once (recommended). +Optionally, you can replace 4 with the number you want to do at once, but this is the recommended value. +::: + +Hardware hacks can be enabled using the `-renderhacks` parameter, followed by one of the below options: + +```ini +- af = AutoFlush +- cpufb = CPU Framebuffer Conversion +- dds = Disable Depth Support +- dpi = Disable Partial Invalidation +- dsf = Disable Safe Features +- tinrt = Texture in Render Target +- plf = Preload Frame Data +``` + +You can string them together like `afcpufbddsdpidsftinrtplf` or separate with commas/colons and it will split them out. + +Run the python script to generate a baseline: + +```sh +python test_run_dumps.py -runner path\to\baseline-build\pcsx2-gsrunnerx64-avx2.exe -dumpdir path\to\results\baseline -gsdir path\to\gs\dumps -renderer vulkan +``` + +:::info +Renderer options are 'auto', 'dx11', 'dx12', 'gl', 'vulkan' or 'sw' +::: + +Run the python script again to generate a test set: + +```sh +python test_run_dumps.py -runner path\to\modified-build\pcsx2-gsrunnerx64-avx2.exe -dumpdir path\to\results\modified -gsdir path\to\gs\dumps -renderer vulkan +``` + +:::info +Renderer options are 'auto', 'dx11', 'dx12', 'gl', 'vulkan' or 'sw' +::: + +Now, you can compare them: + +```sh +python test_check_dumps.py -baselinedir path\to\results\baseline -testdir path\to\results\modified changes.html +``` + +It will log any different frames to both the terminal, as well as the HTML file you specify. diff --git a/docs/advanced/miscellaneous.md b/docs/advanced/miscellaneous.md new file mode 100644 index 0000000..3000a33 --- /dev/null +++ b/docs/advanced/miscellaneous.md @@ -0,0 +1,222 @@ +--- +title: "Miscellaneous" +summary: "Extra Stuff" +draft: false +toc: true +sidebar_position: 5 +--- + +## Using GDB with Linux AppImages (32 bit and 64 bit) + +This guide is useful if for example you'd like to debug a 32 bit crash but cannot build a 32 bit PCSX2. + +1. **Put your AppImage into a directory by itself** + + We'll call the AppImage `PCSX2.AppImage` and then navigate your terminal to this directory.. + +2. **Extract the contents of the AppImage** + + You can do this by doing `./PCSX2.AppImage --appimage-extract` + + A new directory called `squashfs-root` should have been created. + +3. **Run the AppImage normally** + + `./PCSX2.AppImage` + +4. **Get the PID of the current PCSX2 instance** + + You can do `pidof PCSX2`. + + If there is more than one pid that shows up, you have more than one PCSX2 running! + + We'll call your running pid `` + +5. **Attach GDB (during a fault or when PCSX2 is running normally, doesn't matter)** + + :::note + You might need to run gdb with `sudo` + ::: + + `gdb squashfs-root/usr/bin/PCSX2 -p ` + + `set sysroot ./squashfs-root` + + `set solib-search-path ./squashfs-root/usr/lib` + + The last two commands are due to the fact that the AppImage runs in a sanboxed area. + It points gdb to where PCSX2 is going to look for libraries for example. + +The commands in-order are listed below: + +```sh +./PCSX2.AppImage --appimage-extract + +./PCSX2.AppImage + +pidof PCSX2 + +gdb squashfs-root/usr/bin/PCSX2 -p + +set sysroot ./squashfs-root + +set solib-search-path ./squashfs-root/usr/lib +``` + +You now have GDB set up and connected to your PCSX2 + +## Viewing Windows Minidumps on Other Platform + +If you're on Windows, the best way to view crash dumps is to open them in Visual Studio. Therefore, you can ignore these instructions if you are on Windows. + +:::warning +You will need the user's crash dump (.dmp) file, and the symbols (.pdb) and executable (.exe) of PCSX2 that is the _exact_ version the user was using when the crash dump was generated. +::: + +### Dependencies + +First off, you will need the `cargo` package manager for rust. Optionally you can build the dependencies from source, but it's much simpler relying on cargo. + +Install the crates [dump_syms](https://crates.io/crates/dump_syms) and [minidump-stackwalk](https://crates.io/crates/minidump-stackwalk) + +```bash +cargo install dump_syms minidump-stackwalk +``` + +Depending on your system, you may need to add the cargo bin directory to `$PATH`, please consult your system specific documentation on how to do this. + +### Generating the Symbols + +`minidump-stackwalk` doesn't support pdb files. This is where `dump_syms` come in handy. + +`dump_syms` will take all available information from the executable and PDB file and convert it into a format `minidump-stackwalk` can interpret. `dump_syms` emits the symbols to STDOUT, so pipe that to a brand new file. + +```bash +dump_syms pcsx2-qt.exe pcsx2-qt.pdb > dumped_symbols.txt +``` + +### Reading the minidump + +```sh +minidump-stackwalk pcsx2-qt.dmp --symbols-path dumped_symbols.txt +``` + +:::tip +You can optionally pass `--features=unstable-all` if you'd like to see if `minidump-stackwalk` can provide more information. +::: + +The output will be the stack trace of the minidump. if you are lucky, then the thread list will show what thread has crashed, and then you can find the cause from the stack trace. **Usually the first call(s) will be in the kernel**, don't write off the call stack though, it's very important to go back until you find the first call stack that is in our code! + +In the example given below, we can find that an assertion was called (#6) in the startVM function (#7). Because of our debugging information, it even tells us the exact lines in code where this happened. + +```sh +Thread 3 EmuThread (crashed) - tid: 48404 + 0 KERNELBASE.dll + 0x3b699 + rax = 0x0000000000000020 rdx = 0x000000b3e64fa739 + rcx = 0x000001c5245e0000 rbx = 0x000000b3e64fb5c0 + rsi = 0x000000000000b201 rdi = 0xffffffffffffffff + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb3e0 + r8 = 0x000000b300000000 r9 = 0x000000b3e64fa820 + r10 = 0x000000007ffe0385 r11 = 0x0000000200000100 + r12 = 0x000001c5246c0c01 r13 = 0x00007ff73245108e + r14 = 0x0000000000001290 r15 = 0x000000000000b254 + rip = 0x00007ffd74eeb699 + Found by: given as instruction pointer in context + 1 KERNELBASE.dll + 0x3b698 + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb418 + rip = 0x00007ffd74eeb699 + Found by: stack scanning + 2 pcsx2-qt.exe! + 0x18951c + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb440 + rip = 0x00007ff73245108e + Found by: stack scanning + 3 pcsx2-qt.exe! + 0x1352c7 + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb458 + rip = 0x00007ff7323fce39 + Found by: stack scanning + 4 pcsx2-qt.exe!WriteMinidump(HINSTANCE__*, void*, void*, unsigned long, unsigned long, _EXCEPTION_POINTERS*, _MINIDUMP_TYPE) [CrashHandler.cpp : 59 + 0x17] + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb468 + rip = 0x00007ff73214f5d2 + Found by: stack scanning + 5 pcsx2-qt.exe!WriteMinidumpAndCallstack(_EXCEPTION_POINTERS*) [CrashHandler.cpp : 124 + 0x3c] + rsi = 0x0000000000000000 rdi = 0x00000000000012a8 + rbp = 0x000000000000bd14 rsp = 0x000000b3e64fb540 + rip = 0x00007ff73214f308 + Found by: call frame info + 6 pcsx2-qt.exe!pxOnAssertFail(char const*, int, char const*, char const*) [Assertions.cpp : 109 + 0x6] + rbx = 0x00007ff7323fdfc1 rsi = 0x0000000000001248 + rdi = 0x00007ff7324202b8 rbp = 0x00000000000000f1 + rsp = 0x000000b3e64fc210 r12 = 0x000000000000006b + r13 = 0x0000000000000000 r14 = 0x00007ff7323fc125 + r15 = 0x000000b3e64fc280 rip = 0x00007ff732150d40 + Found by: call frame info + 7 pcsx2-qt.exe!EmuThread::startVM(std::shared_ptr) [QtHost.cpp : 241 + 0x1e] + rbx = 0x000001c638e0bd20 rsi = 0x000000b3e64fc680 + rdi = 0x000001c52891b2f0 rbp = 0x000000b3e64fc759 + rsp = 0x000000b3e64fc4d0 r12 = 0x000001c638e0bd20 + r13 = 0x0000000000000000 r14 = 0x000001c52891b2f0 + r15 = 0x000001c52891b2f0 rip = 0x00007ff731e3e04e + Found by: call frame info + 8 pcsx2-qt.exe!EmuThread::qt_static_metacall(QObject*, QMetaObject::Call, int, void**) [moc_QtHost.cpp : 591 + 0x1f] + rbx = 0x000001c638e0bd20 rsi = 0x000001c52891b2f0 + rdi = 0x000001c638e0bd20 rbp = 0x000000b3e64fc759 + rsp = 0x000000b3e64fc600 r12 = 0x000001c638e0bd20 + r13 = 0x0000000000000000 r14 = 0x000001c52891b2f0 + r15 = 0x000001c52891b2f0 rip = 0x00007ff731df86fa + Found by: call frame info + 9 Qt6Core.dll + 0xe7b98 + rbx = 0x000001c638e0bd20 rsi = 0x000001c52891b2f0 + rbp = 0x000000b3e64fc759 rsp = 0x000000b3e64fc6a0 + r12 = 0x000001c638e0bd20 r13 = 0x0000000000000000 + r14 = 0x000001c52891b2f0 r15 = 0x000001c52891b2f0 + rip = 0x00007ffd2eb27b99 + Found by: call frame info +``` + +Here is the exact same crash, without debugging information. + +```sh +Thread 3 EmuThread (crashed) - tid: 48404 +0 KERNELBASE.dll + 0x3b699 + rax = 0x0000000000000020 rdx = 0x000000b3e64fa739 + rcx = 0x000001c5245e0000 rbx = 0x000000b3e64fb5c0 + rsi = 0x000000000000b201 rdi = 0xffffffffffffffff + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb3e0 + r8 = 0x000000b300000000 r9 = 0x000000b3e64fa820 + r10 = 0x000000007ffe0385 r11 = 0x0000000200000100 + r12 = 0x000001c5246c0c01 r13 = 0x00007ff73245108e + r14 = 0x0000000000001290 r15 = 0x000000000000b254 + rip = 0x00007ffd74eeb699 + Found by: given as instruction pointer in context + 1 KERNELBASE.dll + 0x3b698 + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb418 + rip = 0x00007ffd74eeb699 + Found by: stack scanning + 2 pcsx2-qt.exe + 0xc6108d + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb440 + rip = 0x00007ff73245108e + Found by: stack scanning + 3 pcsx2-qt.exe + 0xc0ce38 + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb458 + rip = 0x00007ff7323fce39 + Found by: stack scanning + 4 pcsx2-qt.exe + 0x95f5d1 + rbp = 0x000000b3e64fb520 rsp = 0x000000b3e64fb468 + rip = 0x00007ff73214f5d2 + Found by: stack scanning + 5 KERNELBASE.dll + 0x67eab + rsp = 0x000000b3e64fb470 rip = 0x00007ffd74f17eac + Found by: stack scanning + 6 pcsx2-qt.exe + 0x95f5d1 + rsp = 0x000000b3e64fb4a0 rip = 0x00007ff73214f5d2 + Found by: stack scanning + 7 pcsx2-qt.exe + 0xc0ce38 + rsp = 0x000000b3e64fb4b0 rip = 0x00007ff7323fce39 + Found by: stack scanning + 8 pcsx2-qt.exe + 0x95f637 + rsp = 0x000000b3e64fb4c0 rip = 0x00007ff73214f638 + Found by: stack scanning + 9 dbgcore.dll + 0x6c3f + rsp = 0x000000b3e64fb4d0 rip = 0x00007ffd526d6c40 + Found by: stack scanning +``` diff --git a/docs/advanced/psx.md b/docs/advanced/psx.md new file mode 100644 index 0000000..5f80209 --- /dev/null +++ b/docs/advanced/psx.md @@ -0,0 +1,58 @@ +--- +title: "PSX Mode" +summary: "About PCSX2's PSX Mode" +draft: false +toc: true +sidebar_position: 4 +--- + +## Can PCSX2 run PSX games? + +:::caution +PCSX2 can run some PSX (PS1) games but this feature is **highly experimental and not intended for general use**. Expect plenty of visual bugs, hangs and low compatibility in general. + +- We **DO NOT** accept Github issues for PSX games. +- We **DO NOT** provide support for PSX games. +- PSX mode is provided **AS-IS** for the purposes of research and testing. + +Instead, please consider using one of the many PSX emulators that already exist. We recommend [DuckStation](https://github.com/stenzek/duckstation/releases/tag/latest). +::: + +--- + +This page documents the development of PSX backward compatibility in PCSX2. + +## How the hardware does it (early consoles) + +- IOP reconfigures from being a sub processor to being the main CPU. Clock speed is reduced from 36.864Mhz to 33.8688Mhz. Sound sample rate decreases from 48Khz to 41.1Khz. +- EE (and GS) reconfigure to being a sub device to the new CPU, emulating the PSX GPU. IOP talks to this GPU via the PGIF device which is actual hardware on the EE. +- IOP sends data to PGIF using DMA channel 2 and the EE+GS combo takes that data to draw graphics. +- To PSX software, it looks like it was talking to a regular PSX GPU while the EE+GS GPU emulation outputs visuals using PS2 hardware. +- Important: Unlike real PSX consoles, the PS2 implementation does not properly switch video modes (PAL / NTSC). + All the settings that make up a valid PAL / NTSC mode are set only once, when ps1driver starts up, and they get set according to the console region (though this can be tricked on real hardware). + Once the console is in PSX mode, software can still cause a 'mode change', but this will not affect the real GS video timings. In effect, it only changes the image position offsets. (Modchips for real hardware offer settings like a 'Y-Fix' to shift the image up and down to counteract this behaviour, though they do nothing to fix choppy scrolling, etc.) +- IOP's bus uses a different configuration, accessing controllers and Memory Cards via SIO0 instad of SIO2, for example. +- SPU2 memory is (somehow? via SSBUSC?) limited to 512KB, down from 2MB. Several SPU2 registers are remapped (via SSBUSC?) because they didn't exist in the old SPU. An example is the register for the Reverb(Effect) End Address. It is configurable in SPU2 mode but fixed to 0x7FFFF in SPU mode. In SPU mode, the EEA register doesn't exist. + +## How the hardware does it (later 'slim' consoles) + +- Beginning with consumer hardware (SCPH-7500x), IOP is emulated on a PPC processor (IBM PPC 405GP) with the DECKARD emulator. +- The BIOS versions belonging to these consoles start at v2.20. +- The PGIF implementation doesn't support this configuration yet. So BIOS versions < 2.20 must be used for now. + +## Some device naming and explanation + +### psx-spx + +Martin Korth's excellent documentation of PSX hardware [here](https://problemkaputt.de/psx-spx.htm). + +### SIO + +- SIO0 is the PS1 Controllers & MC interface. It is an SPI port. +- SIO1 is the PS1 Serial port on the back of the early PS1 models. It is a UART Serial port. +- SIO2 is the PS2 Controllers & MC port(s). It is SPI and similar to SIO0, but more complex, with separate channels for each controller & MC and supporting higher speeds. + +### SBUS, SSBUS, SSBUSC + +The SSBUSC can be controlled to some extent (unlike the SBUS). See psx-spx Memory Control (the address & delay registers for different devices) and SSBUSC in fps2bios. The SSBUS is what connects the IOP peripherals to the IOP bus interface (SSBUSC), which interfaces to the IOP's System Bus, which connects through some buffers and other (address/data multiplexing hardware most likely) to the SBUS. When I say IOP System Bus, I mean the internal bus, while when I say SBUS (or PS1 System Bus), I am referring to the bus that connects the IOP & EE. +The SBUS is an extension to the IOP's System Bus (and that is what it stands for anyway). On the PS1 it connects IOP to GPU and on the PS2 IOP and EE. Rightfully, the PGIF is an EE hardware that emulates the PS1 GPU registers, so that accessing them through the SBUS (like on the PS1) would work the same as on a PS1. The SBUS on a PS2 corresponds to the System Bus (not the internal, the external one) of a PS1. diff --git a/docs/contributing/advanced_formatting.md b/docs/contributing/advanced_formatting.md new file mode 100644 index 0000000..9b9157d --- /dev/null +++ b/docs/contributing/advanced_formatting.md @@ -0,0 +1,690 @@ +--- +title: "Advanced Code Formatting Guidelines" +summary: "PCSX2 Project Coding Guidelines" +draft: false +toc: true +sidebar_position: 3 +--- + +Coding guidelines for the entire PCSX2 project. + +:::note +This guideline is subject to change as the need arises. +::: + +- [General Rules](#general-rules) + - [Use Tabs For Indentation](#use-tabs-for-indentation) + - [Indent Namespaces](#indent-namespaces) + - [Indent Members](#indent-members) + - [No Indentation For Labels](#no-indentation-for-labels) + - [Place The Public API First](#place-the-public-api-first) + - [Use Descriptive Names](#use-descriptive-names) + - [Avoid Operator Overloading](#avoid-operator-overloading) + - [Use Scoping Where Applicable](#use-scoping-where-applicable) +- [Variables](#variables) + - [Snake Case For Variable Names](#snake-case-for-variable-names) + - [Prefix Member Variables With `m_`](#prefix-member-variables-with-m_) + - [Prefix Static Variables With `s_`](#prefix-static-variables-with-s_) + - [Mark Variables `const` Where Applicable](#mark-variables-const-where-applicable) + - [Encapsulate](#encapsulate) + - [Prefer STL Containers Where Applicable](#prefer-stl-containers-where-applicable) + - [Prefer `static constexpr` For Compile Time Constants](#prefer-static-constexpr-for-compile-time-constants) +- [Functions](#functions) + - [Camel Case For Function Names](#camel-case-for-function-names) + - [Avoid Excessive/Non-Obvious Parameter Usage](#avoid-excessivenon-obvious-parameter-usage) + - [Mark Member Functions `const` Where Applicable](#mark-member-functions-const-where-applicable) +- [Types](#types) + - [Capital Case For Type Names](#capital-case-for-type-names) + - [Reference And Pointer Specifiers](#reference-and-pointer-specifiers) + - [Use Type Aliasing Where Applicable](#use-type-aliasing-where-applicable) + - [Namespace Enums](#namespace-enums) + - [Use Enum Types Explcitly](#use-enum-types-explcitly) +- [Control Statements](#control-statements) + - [Space Following The Keyword](#space-following-the-keyword) + - [Use Spaces, Newlines And Intermediate Variables](#use-spaces-newlines-and-intermediate-variables) + - [Braces On Seperate Lines](#braces-on-seperate-lines) + - [Prefer Ranged For Loops](#prefer-ranged-for-loops) +- [Preprocessor](#preprocessor) + - [Use `#pragma once`](#use-pragma-once) +- [Comments](#comments) + - [Use `//`](#use-) + - [Avoid The Obvious](#avoid-the-obvious) + - [Denote And Explain All Hacks](#denote-and-explain-all-hacks) + +## General Rules + +### Use Tabs For Indentation + +```cpp +// good +{ + int foo = 0; +} + +// bad +{ + int foo = 0; +} +``` + +:::warning +Always use tabs (4 width) for indentation. **No exceptions**. +::: + +[Visual Studio Guide](https://docs.microsoft.com/en-us/visualstudio/ide/reference/options-text-editor-c-cpp-formatting?view=vs-2019) + +### Indent Namespaces + +```cpp +// good +namespace Util +{ + class File + { + + }; +} + + +// bad +namespace Util +{ +class File +{ + +}; +} +``` + +### Indent Members + +```cpp +// good +class Texture +{ +public: + GSVector4i getSize() const; + +private: + GSVector4i m_size; +}; + +// bad +class Texture +{ +public: +GSVector4i getSize() const; + +private: +GSVector4i m_size; +}; +``` + +### No Indentation For Labels + +```cpp +// good +class Texture +{ +public: + bool isValid() const; + +private: + bool m_valid; +}; + +// bad +class Texture +{ + public: + bool isValid() const; + + private: + bool m_valid; +}; +``` + +### Place The Public API First + +```cpp +// good +class Texture +{ +public: + bool isValid() const; + GSVector4i getSize() const; + + void setValid(); + void setInvalid(); + void setSize(const GSVector4i& size); +private: + bool m_valid; + GSVector4i m_size; + + void onResize(); +} + +``` + +:::tip +Don't distract other developers with implementation details. Place the public API first where it is easy to find. +::: + +### Use Descriptive Names + +```cpp +// good +GSVector4i display_offset; +GSVector4i getDisplayOffset(); + +// bad +GSVector4i off; +GSVector4i getOffset(); +``` + +:::tip +Always use descriptive names when declaring variables and functions. + +**Do not** shorten variable names for the sake of saving a few keystrokes. Code is meant to be easily read not easily written. +::: + +### Avoid Operator Overloading + +```cpp +// good +auto sizer = new wxStaticBoxSizer(wxVERTICAL, this, L"Sizer"); +sizer->Add(some_panel, StdExpand()); + +// awful +auto& sizer (*new wxStaticBoxSizer(wxVERTICAL, this, L"Sizer" )); +sizer += some_panel | StdExpand(); +``` + +Do not make excessive use of operator overloading. + +**Exception:** Some types are condusive to mathmatical operator overloading such as a simd or other wrapper type. + +**Exception:** Sometimes it is acceptable to overload the assignment, move assignment or comparison operators. + +### Use Scoping Where Applicable + +```cpp +// good +// scope denotes a critical section +{ + std::lock_guard lk(mutex); + // ... +} + +// good +// prevents a hack from polluting local scope +{ + // HACK: Nvidia cards have an alignment issue + const bool should_offset = m_device->isNvidia() && m_hacks_enabled; + if (should_offset) + { + + } +} + +// good +// scope helps prevent name collisions in a large function +bool CreateState() +{ + { + D3D11_DEPTH_STENCIL_DESC depth_stencil_desc = {}; + depth_stencil_desc.DepthEnable = false; + depth_stencil_desc.DepthWriteMask = D3D11_DEPTH_WRITE_MASK_ZERO; + depth_stencil_desc.DepthFunc = D3D11_COMPARISON_NEVER; + + HRESULT result = E_FAIL; + result = m_device->CreateDepthStencilState( + &depth_stencil_desc, &m_depth_no_write + ); + + if (FAILED(result)) + return false; + } + + { + D3D11_DEPTH_STENCIL_DESC depth_stencil_desc = {}; + depth_stencil_desc.DepthEnable = true; + depth_stencil_desc.DepthWriteMask = D3D11_DEPTH_WRITE_MASK_ALL; + depth_stencil_desc.DepthFunc = D3D11_COMPARISON_ALWAYS; + + HRESULT result = E_FAIL; + hr = m_dev->CreateDepthStencilState( + &depth_stencil_desc, &m_depth_write + ); + + if (FAILED(result)) + return false; + } + + return true; +} +``` + +## Variables + +### Snake Case For Variable Names + +```cpp +// good +int current_offset; + +// bad +int currentOffset; +int CurrentOffset; +``` + +### Prefix Member Variables With `m_` + +```cpp +class Texture +{ + // good + bool m_valid; + // bad + GSVector4i size; +} +``` + +### Prefix Static Variables With `s_` + +```cpp +// good +static s_device; + +// bad +static device; +``` + +### Mark Variables `const` Where Applicable + +```cpp +// good - not going to change +const bool is_valid = texture && texture->isValid(); + +// good - deonte function won't modify the reference +void checkSize(const GSVector4i& size); +``` + +### Encapsulate + +```cpp +// good +auto size = texture->getSize(); +if (texture->isValid()) +{ + +} + +// bad +auto size = texture->m_size; +if (texture->m_valid) +{ + +} +``` + +### Prefer STL Containers Where Applicable + +```cpp +// good +std::array foo; +std::unique_ptr bar; + +// bad +int foo[2]; +int* bar; +``` + +:::tip +**Exception:** It is a common idiom in gui toolkits such as wx to use raw pointers. In those instances you should prefer raw pointers to smart pointers. +::: + +### Prefer `static constexpr` For Compile Time Constants + +```cpp +// good +class Texture +{ + static constexpr MAX_BUFFER_SIZE = 1920 * 1080; + using BufferType = std::array; + + BufferType m_data; +} + +// bad +#define MAX_BUFFER_SIZE 20736000 +class Texture +{ + using BufferType = std::array; + BufferType m_data; +} + +``` + +## Functions + +### Camel Case For Function Names + +```cpp +// good +GSVector4i getSize(); + +// bad +GSVector4i get_size(); +GSVector4i GetSize(); +``` + +All functions (global, member or otherwise) must be in camelCase form. + +### Avoid Excessive/Non-Obvious Parameter Usage + +```cpp +// good +TextureCache::LookupInfo lookup_info = {}; +lookup_info.base = 0x0; +lookup_info.buffer_wdith = 10; +lookup_info.psm = PSM::CT32; +lookup_info.rectangle = GSVector4i(0, 0, 64, 64); + +auto texture = m_texture_cache->Search(lookup_info); + +// bad - not obvious +auto texture = m_texture_cache->Search(0x0, 10, PSM::CT32, 0, 0, 64, 64); +auto texture = m_texture_cache->Search({0x0, 10, PSM::CT32, 0, 0, 64, 64}); +``` + +Avoid parameter usage which is non-obvious. Try to keep functions with in a reasonable amount of parameters. Consider the use of a `struct` in instances where this is not avoidable. + +:::info +The Windows calling convention passes the first 2 arguments (4 in x64) as registers. +::: + +### Mark Member Functions `const` Where Applicable + +```cpp +class Texture +{ +private: + GSVector4i m_size; + bool m_valid; +public: + // good + GSVector4i getSize() const + { + return m_size; + } + + // bad - doesn't modify the object, use const + bool isValid() + { + return m_valid; + } +} +``` + +## Types + +### Capital Case For Type Names + +```cpp +// good +struct LookupInfo; +class CachedTexture; +enum ColorFormat; + +// bad +struct lookupInfo; +class cached_texture; +enum COLOR_FORMAT; +``` + +### Reference And Pointer Specifiers + +```cpp +// good +int& foo; +int&& foo; +int* bar_ptr; +int** ptr; + +// bad +int &foo; +int &&foo; +int *bar; +int **bar; +``` + +:::warning +Reference and pointer specifiers follow the type name and are immediately followed by a space. **No exceptions**. +::: + +### Use Type Aliasing Where Applicable + +```cpp +// good +using BufferType = std::array; + +BufferType buffer1; +BufferType buffer2; +BufferType buffer3; + +// bad +std::array buffer1; +std::array buffer2; +std::array buffer3; +``` + +In addition to making the code more readable, this makes it easier to modify a shared type. + +### Namespace Enums + +```cpp +// good +namespace Format +{ + enum PSM + { + CT32 = 0x0, + CT24 = 0x1, + // ... + }; +} + +case Format::PSM::CT32: +case Format::CT24: + +// bad - pollutes the global namespace +enum PSM +{ + PSMCT32 = 0x0, + PSMCT24 = 0x1, + // ... +}; +``` + +### Use Enum Types Explcitly + +```cpp +namespace Color +{ + enum Format; +} + +// good +void setFormat(Color::Format format); + +// bad +void setFormat(int format); +``` + +## Control Statements + +### Space Following The Keyword + +```cpp +// good +if (check) +while (true) +for (const auto& item : items) + +// bad +if(check) +while(true) +for(const auto& item : items) +``` + +### Use Spaces, Newlines And Intermediate Variables + +```cpp +// good +if (some_long_variable || + some_other_variable && + some_other_long_variable) +{ + +} + +// good +const bool check = some_long_variable || + some_other_variable && + some_other_long_variable; + +if (check) +{ + +} + +// bad +if (some_long_variable || some_other_variable && some_other_long_variable) + +``` + +### Braces On Seperate Lines + +```cpp +// good +for (const auto& item : items) +{ + // do something with item +} + +// good +if (check) +{ + +} + +// bad +if (check) { + +} + +// awful +if (check) { doSomething(); } +if (check) doSomething(); +``` + +:::tip +**Exception:** In the event that the body of the control statement is one line, the braces can be omitted. +::: + +```cpp +// this is acceptable +if (some_check) + doSomething(); +``` + +### Prefer Ranged For Loops + +```cpp +// good +for (const auto& texture : cached_textures) +{ + auto size = texture->getSize(); + // ... +} + +// bad +for (int i = 0; i < cached_texture.size(); i++) +{ + auto size = textures[i]->getSize(); + // ... +} +``` + +## Preprocessor + +### Use `#pragma once` + +```cpp +// good +#pragma once +class Texture +{ + +} + +// bad - define guard +#ifndef TEXTURE +#define TEXTURE +class Texture +{ + +} +#endif +``` + +## Comments + +### Use `//` + +```cpp +// good +// an invalid texture here means we are recovering +// from an ealier error + +// bad +/* +an invalid texture here means we are recovering +from an ealier error +*/ +``` + +:::tip +Prefer the usage of `//` for all comments. Developers commonly need to comment an entire block of code and having a `/* */` style comment in the middle often causes problems. +::: + +### Avoid The Obvious + +```cpp +// good +// an invalid texture here means we are recovering +// from an earlier error +if (!texture->isValid()) +{ + +} + +// bad +// check if the texture is valid +if (!texture->isValid()) +{ + +} +``` + +:::tip +Avoid comments which outright state what the code is doing. Try to make comments describe what _isn't_ obvious about the code. +::: + +### Denote And Explain All Hacks + +```cpp +// good +// HACK: The data cache is too slow to reasonably emulate +``` diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md new file mode 100644 index 0000000..1152fcc --- /dev/null +++ b/docs/contributing/contributing.md @@ -0,0 +1,68 @@ +--- +title: "Contributing to PCSX2" +summary: "Getting started with contributing to PCSX2" +draft: false +toc: true +sidebar_position: 1 +--- + +In this section you will learn how to contribute to PCSX2. + +As a first step, please review these links as they'll help you understand how the development of PCSX2 works. + +- [How to Contribute](#how-to-contribute) +- [Just Starting Out](#just-starting-out) +- [Pull Request Guidelines](#pull-request-guidelines) +- [General Documentation And Coding Strategies](#general-documentation-and-coding-strategies) + +## How to Contribute + +If you have no experience in programming or just want to help us in any shape or form, here is what you can do: + +- If you find application or emulation bugs, feel free to [report an issue on our GitHub](https://github.com/PCSX2/pcsx2/issues) +- If you have a knack for writing articles or testing games in general, we are always looking for help! + - Please join our [Discord](https://pcsx2.net/discord) if you are interested! +- A game runs well or has a weird workaround? Head over to [the Wiki](https://wiki.pcsx2.net/Main_Page) and let us know on [Discord](https://pcsx2.net/discord)! +- Want to help translating PCSX2 to your language? Head over to [Crowdin](https://crowdin.com/project/pcsx2-emulator) and start right away! + +However if you do have experience in programming and wanted to contribute code, read on! + +## Just Starting Out + +- If you're unfamilar with git, check out this [brief introduction to Git](./git.md) +- [How to build PCSX2 for Windows](../advanced/building.md#building-on-windows) +- [How to build PCSX2 for Linux](../advanced/building.md#building-on-linux) + +## Pull Request Guidelines + +The following is a list of _general_ style recommendations that will make reviewing and merging easier: + +- Commit Messages + + - Please try to prefix your commit message, indicating what area of the project was modified. + + - For example `GS: message...`. + - Looking at the project's commit history will help with keeping prefixes consistent overtime, _there is no strictly enforced list_. + + - Try to keep messages brief and informative + + - Remove unnecessary commits and squash commits together when appropriate. + - If you are not familiar with rebasing with git, check out the following resources: + - [CLI](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history) + - [GUI (SourceTree)](https://www.atlassian.com/blog/sourcetree/interactive-rebase-sourcetree) + +- Code Styling and Formatting + + - [Consult the style guide](./formatting.md) + + - Run `clang-format` using the configuration file in the root of the repository + - [Visual Studio Setup](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/) + - IMPORTANT - if you are running `clang-format` on unrelated changes (ie. formatting an entire file), please do so in a separate commit. + - If you cannot scope your `clang-format` to just your changes and do not want to format unrelated code. Try your best to stick with the existing formatting already established in the file in question. + +## General Documentation And Coding Strategies + +- [Commenting Etiquette](../troubleshooting/identify.md#commenting-etiquette) + +- [Coding style](./formatting.md) + - [More comprehensive style-guide](./advanced_formatting.md) diff --git a/docs/contributing/formatting.md b/docs/contributing/formatting.md new file mode 100644 index 0000000..b34b836 --- /dev/null +++ b/docs/contributing/formatting.md @@ -0,0 +1,76 @@ +--- +title: "Code Formatting Guidelines" +summary: "PCSX2's Formatting Guidelines" +draft: false +toc: true +sidebar_position: 2 +--- + +Basic code formatting guide that you should take into account. + +To help with code readability, please follow these basic code‐formatting guidelines. Doing so will greatly help both you, other contributors, the PCSX2 team and everyone else. + +## Topic 1: Do not use variable type prefixes + +Variable type prefixes are commonly known as [Hungarian Notation](https://en.wikipedia.org/wiki/Hungarian_notation), and are the sort of variable names popularized by the `Win32API`. They look something like this is in ideal situations: + +```C++ +DWORD dwSomeDoubleWord; +``` + +Besides being unreadable and looking terrible, this naming convention is totally impractical for modern programming via an IDE with autocomplete features. Coders using such tools want to do autocomplete by the subject of the variable's purpose, and are then automatically provisioned variable type information via tooltip, making the prefix nearly worthless. If you're looking for the `MasterVolume` of a voice, you might think `VoiceVolumeMaster`, `MasterVolumeVoice`, or `VolumeVoiceMaster` and in fact you'll probably have no idea of it's a dword, word, int, or float value type. Any code using this naming convention will be changed to something more sensible. + +**Just don't do it. _Ever._** + +## Topic 2: Using PCSX2 base types instead of C/C++ atomic types + +Most of the time you want to use either PCSX2 cross-platform types in the place of C++ atomic types. Most of the common types are: + +```C++ +u8, s8, u16, s16, u32, s32, u64, s64, u128, s128, uptr, sptr +``` + +These types ensure consistent operand sizes on all compilers and platforms, and should be used almost always when dealing with integer values. There are exceptions where the plain int type may be more ideal, however: typically C++ compilers define an `int` as a value at least 32 bits in length (upper range is compiler/platform specific), and temporary arithmetic operations often conform to this spec and thus can use `int` (a compiler may be allowed then to use whichever data type the target CPU is most efficient at handling). Other C++ integer types such as `short` and `long` should not be used for anything except explicit matching against externally defined 3rd party library functions. They are too unpredictable and have no upside over strict operand sizing. + +:::note +Using the C++ atomic types `float` and `double` are acceptable; there are no defined alternatives at this time. +::: + +:::info +PCSX2-specific types `uptr` and `sptr` are meant to be integer-typed containers for pointer addresses, and should be used in situations where pointer arithmetic is needed. `uptr/sptr` definitions are not type safe and `void*` or `u8*` should be used for parameter passing instead, when possible. +::: + +## Topic 3: Do not use `private` class members; use `protected` instead + +There is no justifiable reason for any class in PCSX2 to use private variable members. Private members are only useful in the context of _dynamically shared core libraries_, and only hinder the object extensibility of non-shared application code. Use `protected` for all non-public members instead, as it protects members from unwanted public access while still allowing the object to be extended into a derived class without having to waste a lot of silly effort to dance around private mess. + +## Topic 4: Name Protected Class Members with `'m_'` + +It is highly recommended to prefix protected class members with `m_`; such as `m_SomeVar` or `m_somevar`. This is a widely accepted convention that many IDEs are adding special built in support and handling for, and for that reason it can help improve class organization considerably for all contributors to the project. However, like most other guidelines it is not a definitive requirement. + +## Topic 5: Avoid compounding complex operations onto a single line with a function declaration + +**Example:** + +```C++ +// Not so good... +void DoSomething() { Function1(); Function2(); var += 1; } + +// Good... +void DoSomething() +{ + Function1(); Function2(); var += 1; +} +``` + +The reason for this guideline is that it can assist debugging tremendously. Most C++ debuggers cannot breakpoint function calls to the bad example, disabling a programmer's ability to use the debugger to quickly track the calling patterns for a function or conditional, and thus removing one of the most ideal tools available to a programmer for understanding code execution patterns of code written by another programmer. For these reasons, code written with such compounding may likely be unrolled onto multiple lines by another programmer at any time, if that programmer is tasked with troubleshooting bugs in that code. + +If the operation of a function is simpler (one or two operations max), and if there are many such functions as part of a class or interface, then compounding on a single line for sake of compact readability may be justified; and in such cases, the programmer should also use the inline_always attribute on the function to denote that it has a trivial and repetitive operation that can be ignored during debugging. + +## Topic 6: Savestate Versioning + +While PCSX2 willfully makes no promise to retain backwards support for savestates, it is none the less a convenience for developer, tester, and user alike when we do. So when possible it is recommended that programmers making changes to the savestate code (normally denoted as a Freeze() function) be sure to increment the savestate version in `Savestate.h` and, if you know how, implement backward support for the old version (if not, then simply increment the savestate version and let someone else fix the backwards compatibility in a later revision). This allows PCSX2 to at the very least fail gracefully when encountering an unknown savestate, and ideally it allows for another coder familiar with the system to properly implement backwards compatibility with the older savestate revision. + +## Topic 7: Shader Cache Versioning + +Similar to savestate versioning, be sure to increment the shader cache version in `ShaderCacheVersion.h` whenever any of the contents of the shaders changes to invalidate the outdated shader cache. diff --git a/docs/contributing/git.md b/docs/contributing/git.md new file mode 100644 index 0000000..e42340c --- /dev/null +++ b/docs/contributing/git.md @@ -0,0 +1,98 @@ +--- +title: "Git Survival Guide" +summary: "Getting Started with Git" +draft: false +toc: true +sidebar_position: 4 +--- + +Getting Started with Git. + +There are lots of guides and documents on the internet, but there are too many and many are confusing. Here is a mini guide to use git with a minimal number of commands and parameters. You won't find any details or explanation of Git's internal mechanisms here. + +## General + +### Remote Transfer or how to communicate with the world + +- Get a fresh repository: `git clone ` +- Update current repository to latest: `git fetch -v` +- Update current repository with commit from a fork: `git fetch -v ` +- Send your new commit to the remote: `git push ` + +### Commit or how to communicate with your local repository + +- Stage your change with dynamic selection: `git add/rm -p ` +- Commit your change: `git commit` +- Uncommit previous commit: `git reset --soft HEAD~1` +- Unstage your change: `git reset HEAD --` +- Discard your change **forever** with dynamic selection: `git checkout -p -- ` + +### Stash or how to save your precious work + +Stash is very useful. For example, your will use it before/after (push/pop) merge/rebase action + +- Push pending update on the stash: `git stash` +- Get back your update: `git stash pop` +- View content of your stash: `git stash show -p stash@\{0\}` + +### Rebase or how to screw the history + +**Never** rebase commits that were pushed remotely. Rebase can be used to improve your current patch set, or to fast-forward-merge after a fetch. + +- The rebase command: `git rebase -i` +- Cancel it: `git rebase --abort` +- Resolve conflict: `git mergetool ` +- Continue rebase: `git rebase --continue` + +### Branch or how to separate your work by feature + +Please note that master is actually the default branch + +- List branches: `git branch -v` +- Switch to another branch: `git checkout ` +- Creates: `git branch ` +- Delete branches: `git branch -d ` +- Set the base reference of the branch (for rebase): `git branch --set-upstream-to= ` + +### House keeping + +- Deletes all stale remote-tracking branches under ``: `git remote prune ` +- List merged branch (safe to delete): `git branch --merged` + +### Updating submodules + +- Clone with submodule: `git clone --recursive -submodules` +- If already cloned: `git submodule update --init --recursive` + +## Git use case example + +### Branch management + +Let's say you want to rebase your current branch topic-v1 to topic-v2 with new additions. Note: topic-v1 could also be master too. + +- Go to current branch: `git checkout topic-v1` +- Create a new one: `git branch topic-v2` +- Go into the new branch: `git checkout topic-v2` +- Set the reference: `git branch --set-upstream-to=origin/master topic-v2` +- Rebase: `git rebase -i` +- ... + +### Split commit + +- Copy your repository if you're not confident with this kind of operation: cp -a `` `` +- Do a rebase: `git rebase -i` +- Use edit on the commit that you want to split + ... rebase on-going... +- Uncommit: `git reset --soft HEAD~1` +- Unstage: `git reset HEAD --` + +At this stage of operation, you get all your changes in the local files, but nothing is ready to be committed. + +Repeat the 2 next commands for each new commits that you want to create + +- Stage your change with dynamic selection: `git add/rm -p ` +- Commit your change: `git commit` + +Once you have finished to split your commit: + +- Finish the rebase: `git rebase --continue` diff --git a/docs/contributing/translation.md b/docs/contributing/translation.md deleted file mode 100644 index 2027cc2..0000000 --- a/docs/contributing/translation.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Translation" -date: 2024-03-20 -summary: "Everything related to translations" -draft: false -toc: true -sidebar_position: 1 ---- - -Want to help translating PCSX2 to your language? Head over to [Crowdin](https://crowdin.com/project/pcsx2-emulator) and start right away! diff --git a/docs/post/cli.md b/docs/post/cli.md index 2a760e1..d5b283e 100644 --- a/docs/post/cli.md +++ b/docs/post/cli.md @@ -1,10 +1,9 @@ --- title: "Command Line Options" -date: 2024-03-20 summary: "List of CLI Commands that are available for PCSX2" draft: false toc: true -sidebar_position: 3 +sidebar_position: 4 --- This section list all the command line option that are available for PCSX2. @@ -20,6 +19,7 @@ Parameter list: -version: Displays version information and exits. -batch: Enables batch mode (exits after shutting down). -nogui: Hides main window while running (implies batch mode). + -portable: Force enable portable mode to store data in local PCSX2 path instead of the default configuration path. -elf : Overrides the boot ELF with the specified filename. -gameargs : passes the specified quoted space-delimited string of launch arguments. -disc : Uses the specified host DVD drive as a source. diff --git a/docs/post/controllers.md b/docs/post/controllers.md index 7cc39a4..b296d88 100644 --- a/docs/post/controllers.md +++ b/docs/post/controllers.md @@ -1,6 +1,5 @@ --- title: "Controllers" -date: 2024-03-20 summary: "Controller Setup Guide" draft: false toc: true @@ -59,6 +58,8 @@ Only use if you are having issues with SDL or XInput. To start mapping your controller, you can first check if your controller is available for automatic mapping by clicking on the "Automatic Mapping" button on the top right. If automatic mapping is not available, you will have to map the buttons to your controller manually. +To manually map a controller, first click on the button you want to map on the virtual controller and then press the corresponding button on your actual controller that you want to bind with the virtual controller. You'll have to do this manually one by one for each button. + :::caution Automatic Mapping is not available for controllers using the DInput source. @@ -88,7 +89,7 @@ Only the original DualShock 3 OEM controllers are compatible with pressure sensi ::: :::info -“DsHidMini is a self-contained, low footprint and feature-rich user-mode driver for Microsoft Windows 10. It presents the controller as a configurable variety of fully standard-compliant HID devices to the system and all games built on common APIs like DirectInput, Raw Input and the low-level HID API. Optional XInput-emulation further increases the support in modern games built with only Xbox controllers in mind.” +DsHidMini is a self-contained, low footprint and feature-rich user-mode driver for Microsoft Windows 10 and Windows 11. It presents the controller as a configurable variety of fully standard-compliant HID devices to the system and all games built on common APIs like DirectInput, Raw Input and the low-level HID API. Optional XInput-emulation further increases the support in modern games built with only Xbox controllers in mind. ::: This allows you to take advantage DualShock 3's pressure sensitive face button on PCSX2. @@ -101,17 +102,29 @@ This allows you to take advantage DualShock 3's pressure sensitive face button o 4. Enable the XInput source in PCSX2. 5. Use "Automatic Binding" button and select XInput. -### Linux and Mac (Experimental) +## Custom profile -The auto binding system doesn't fully support it, but the backend does. +### What is the purpose of a controller profile? -- Bind all your keys, then close PCSX2 and edit the `PCSX2.ini` file to delete all the buttons and change all the axes from `-Axis##` or `+Axis##` to `FullAxis##` +Custom profiles are intended for overriding your normal Shared mappings. You use profiles when you want a completely different controller setup for a specific game. For example, you may create a profile for games which use a guitar controller, rather than changing your mappings every time you play that one game. If you aren't trying to make a special setup for one specific game, don't use profiles. -:::caution -On Linux, [you may need to add udev rules to give PCSX2 access to the controller](https://wiki.rpcs3.net/index.php?title=Help:Controller_Configuration#On_Linux). -::: +### Why isn't my game recognizing my profile? -## Multitap +The Shared profile is what you start out with and is what all games default to, unless told otherwise. When creating a profile, the name prompt tells you to change the input profile in your per-game settings. + +If you want to use a custom profile for a specific game, then you need to assign it to the game. You can find this option on the per-game setting's Summary tab. Right click it in your games list, hit Properties, then select the appropriate item under Input Profile. + +### I am trying to map multiple PC devices to a single PS2 controller + +Profiles do not do this. To map multiple PC devices to a single PS2 controller, simply shift-click a mapping button. You will be given a screen with the ability to add a mapping from a second device (or more). + +### I am trying to change my mappings between two layouts while I play the game + +This is not and will not be a supported feature in PCSX2. Use external software to do this. + +## Peripherals & Accessory + +### Multitap Multitaps are physical devices sold separately for the Playstation 2. A multitap fills both a controller and memory card port, and expands those out to four controller and memory card slots each. @@ -125,8 +138,6 @@ For example, enabling multitap in port 1 will add controllers 1-A through 1-D. T The Playstation 2 SDK places no restrictions on how games use a multitap. Some games will ignore multitapped controllers if you do not multitap a specific port or use specific slots. You will need to refer to your game's manual to understand which port the game supports multitaps for, and in what order a game expects multitapped controllers to be added. -## Peripherals & Accessory - ### Wheel compatibility When setting up your wheel device, you must pick the PS2 wheel that closest matches your PC wheel. Failing to do so may result in broken or missing FFB (Force Feedback), or unresponsive steering. @@ -156,26 +167,6 @@ If your Buzz controllers do not appear in the list of available devices in PCSX2 Your Buzz controller should now be detected by PCSX2. You may need to close and reopen PCSX2 if it is not immediately available. -## Custom profile - -### What is the purpose of a controller profile? - -Custom profiles are intended for overriding your normal Shared mappings. You use profiles when you want a completely different controller setup for a specific game. For example, you may create a profile for games which use a guitar controller, rather than changing your mappings every time you play that one game. If you aren't trying to make a special setup for one specific game, don't use profiles. - -### Why isn't my game recognizing my profile? - -The Shared profile is what you start out with and is what all games default to, unless told otherwise. When creating a profile, the name prompt tells you to change the input profile in your per-game settings. - -If you want to use a custom profile for a specific game, then you need to assign it to the game. You can find this option on the per-game setting's summary tab, Right click it in your games list, hit Properties, then select the appropriate item under Input Profile. - -### I am trying to map multiple PC devices to a single PS2 controller - -Profiles do not do this. To map multiple PC devices to a single PS2 controller, simply shift-click a mapping button. You will be given a screen with the ability to add a mapping from a second device (or more). - -### I am trying to change my mappings between two layouts while I play the game - -This is not and will not be a supported feature in PCSX2. Use external software to do this. - ## Known Issues ### Steam input hijacking diff --git a/docs/post/general.md b/docs/post/general.md index ddc7e0e..0c2d6bc 100644 --- a/docs/post/general.md +++ b/docs/post/general.md @@ -1,6 +1,5 @@ --- title: "General Information" -date: 2024-03-20 summary: "General information in regards to PCSX2 features" draft: false toc: true @@ -69,7 +68,8 @@ Go to `Settings > Game Properties` Portable mode allows you to confine all of PCSX2's related data and configuration into its own folder instead of using the user's Documents folder, essentially making it "Portable". -- To enable portable mode, simply create an empty `portable.ini` file in the root directory of your PCSX2 folder. +- To enable portable mode, simply create an empty `portable.ini` file in the root directory of your PCSX2 folder +- You can also pass in `-portable` as a launch argument to force PCSX2 to run in portable mode ## Save States @@ -136,19 +136,3 @@ Gran Turismo 4 only keeps partial information about your garage in RAM at any ti #### How do I fix this? If you encounter a rewind condition and the game no longer recognizes your memory card, you have no choice but to boot the game again. Do not load a savestate. Let the game boot and load normally from your memory card. - -## PSX (PS1) Compatibility - -PCSX2 can run some PSX (PS1) games but this feature is highly experimental and not intended for general use. Expect plenty of visual bugs, hangs and low compatibility in general. - -Instead, please consider using one of the many PSX emulators that already exist. We suggest [DuckStation](https://github.com/stenzek/duckstation/releases/tag/latest) - -:::warning - -- We **DO NOT** accept Github issues for PSX games. -- We **DO NOT** provide support for PSX games. -- PSX mode is provided **AS-IS** for the purposes of research and testing. - -::: - -If you have read the above warning and are interested in trying PSX games anyway, please refer to the [following thread](https://forums.pcsx2.net/Thread-PSX-Mode-Unofficial-Compatibility-List) diff --git a/docs/post/img/data_directory.webp b/docs/post/img/data_directory.webp new file mode 100644 index 0000000..8f74b06 Binary files /dev/null and b/docs/post/img/data_directory.webp differ diff --git a/docs/post/img/memcard.webp b/docs/post/img/memcard.webp new file mode 100644 index 0000000..f8417e8 Binary files /dev/null and b/docs/post/img/memcard.webp differ diff --git a/docs/post/img/memcard_create.webp b/docs/post/img/memcard_create.webp new file mode 100644 index 0000000..a6c1cfd Binary files /dev/null and b/docs/post/img/memcard_create.webp differ diff --git a/docs/post/img/memcard_folder.webp b/docs/post/img/memcard_folder.webp new file mode 100644 index 0000000..0e51a03 Binary files /dev/null and b/docs/post/img/memcard_folder.webp differ diff --git a/docs/post/img/memcard_python_path.webp b/docs/post/img/memcard_python_path.webp new file mode 100644 index 0000000..8f897cd Binary files /dev/null and b/docs/post/img/memcard_python_path.webp differ diff --git a/docs/post/img/mymcplusplus.webp b/docs/post/img/mymcplusplus.webp new file mode 100644 index 0000000..b048acf Binary files /dev/null and b/docs/post/img/mymcplusplus.webp differ diff --git a/docs/post/memcards.md b/docs/post/memcards.md new file mode 100644 index 0000000..150ea4e --- /dev/null +++ b/docs/post/memcards.md @@ -0,0 +1,162 @@ +--- +title: "Memory Cards" +date: 2024-03-20 +summary: "This guide shows you how to import save data to your virtual memory card" +draft: false +toc: true +sidebar_position: 3 +--- + +This guide shows you information about Memory Cards in general. + +## General + +When you first install PCSX2, it comes with two virtual memory cards that you can use right away. You can also create a new one and even delete any of the existing ones. + + + +### Memory Cards Types + +There are two types of Memory Cards in PCSX2: File Memory Card and Folder Memory Cards. + + + +#### File Memory Card + +File Memory Cards are the standard, most compatible memory card type. They are a single `.ps2` file and they store all the save data inside that file for that particular card. They are also available in multiple sizes: 8MB, 16MB, 32MB and 64MB. 8MB is the most compatible option. If you need a bigger card capacity, refer to Folder Memory Card. + +#### Folder Memory Card + +Folder Memory Cards are a little different from File Memory Cards. Instead of storing all the save data inside a single monolithic `.ps2` file, they store all saves data inside a folder on the host's file system. + +The benefits of this are: + +- Infinite Capacity +- Easier to copy the save data out of the card +- Easier to delete a specific save data on that card + +Keep in mind that save data in a Folder Memory Card is isolated; this means that you can't manage your save data using the PS2 BIOS directly because the game's save data won't show up. + +To be able to manage your save data through the BIOS, you must go into the BIOS's Browser menu and then do a disc change through `System -> Change Disc` and selecting the game that you want to manage the data with. + +:::warning +Using Folder Memory Cards is not without caveats. Some games aren't compatible with Folder Memory Cards. +::: + + + +## Importing Save Data + +Most save files for PlayStation 2 games during the console's lifecycle were extracted from consoles using the various cheat devices which were sold at the time. Some examples are Action Replay Max, Code Breaker, and GameShark. However, because these companies were competing and did not want any other companies to be able to use saves extracted with their devices, the saves were repackaged into proprietary formats and encrypted. To use these save files on PCSX2, they must be decrypted and unpackaged by specialized software. + +### What is MyMC? + +MyMC is software designed to interact with PlayStation 2 memory card images (.ps2) as are used by PCSX2. It allows you to add, remove, and export save data. + +Multiple versions of MyMC have been created over the years. The first release of MyMC was by Ross Ridge, who is responsible for documenting a substantial amount of information on PS2 memory cards. Subsequent updates have been made by other authors, porting the program to a native Python app, and adding support for newer container formats. + +#### MyMC by Ross Ridge + +Ross Ridge's original MyMC program works without issue on Windows 10 and newer and is a Windows-exclusive program. However, it predates the wide availability of PSV files – the format used to extract PS2 saves from a PS3 – and does not have support for these. For non-advanced users on Windows, this is probably the most straightforward version to run, as it is a basic Windows `.exe` file. + +#### MyMC+ Python port by thestr4ng3r + +A Python 3 native port was created by thestr4ng3r which made some adjustments and added some additional features, most notably PSV support. While this version is cross-platform and more feature-complete, we generally feel it has been obsoleted due to some compatibility issues it had with Python libraries such as wxPython, and it has been improved upon by a newer release. We generally recommend not using this version, but it is important to remember it as a stepping stone for the latest revision. + +#### MyMC++ Python port by Adubbz + +A second Python 3 native port is currently our recommended choice for advanced users. This version brings in the improvements from MyMC+ such as cross-platform support and PSV support, adds additional usability improvements, and reliably runs on the latest versions of Python 3. This version also adds support for adding save files to the .mc2 memory card format used by the MemCard PRO2. + +### Using MyMC + +#### Prerequisites + +[The Windows Visual C++ 2008 Runtime (x86) is required](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist#visual-studio-2008-vc-90-sp1-no-longer-supported) + +:::info +The x64 version will not work; you must install the x86 version if you do not have it already. +::: + +#### Download MyMC + +MyMC is a portable program and does not "install". [You can find the original MyMC here](http://www.csclub.uwaterloo.ca:11068/mymc/) + +Download the `mymc-alpha-2.7.zip` file and extract it to a folder of your choice. Launch MyMC by running `mymc-gui.exe`. + +### Using MyMC++ + +#### Prerequisites + +Windows and MacOS users will need to install the [latest version of Python from here.](https://www.python.org/downloads/) + +:::caution +While going through the installer, make sure to check the box to add Python to your PATH. You may need to reboot your PC after installing to ensure your PATH variable is set properly; more on this later. + + +::: + +:::tip +Most Linux distributions come bundled with Python 3 already installed. If your distribution does not include Python 3, you should try first to install it using your distribution's package manager. +::: + +#### Download MyMC++ + +Once Python 3 is installed, you can use its package management command `pip` to automatically download and install MyMC++ for you. Open a command shell and run the following command: + +```sh +pip install mymcplusplus[gui] +``` + +:::caution +When running this command, do not run the `python` command or enter this into a Python shell. Enter this command directly into your operating system's command shell. For Windows users, enter this directly into Command Prompt or Powershell. For Linux and MacOS users, enter this directly into your terminal. +::: + +:::tip +It is recommended that you use `pipx` to install MyMC++ as recent python versions have implemented externally managed environments, which forces you to first manually setup a virtual environment before you can start installing MyMC++. `pipx` will handle all of the process automatically. +::: + +If the above command fails saying that `pip` is an unrecognized command, you have not properly added Python to your PATH variable. Try rebooting first. If the command still fails, look up a guide for how to add Python to your operating system's PATH variable. + +Once `pip` finishes running, you can then run the following command from your operating system's command shell to launch MyMC++: + +```sh +mymcplusplus +``` + +Windows users can optionally type this command into their start menu, and Windows will suggest launching the program there. On any operating system, you can also create a shortcut and set this command as the target. Either of these methods will avoid needing to open a command shell to launch MyMC++. + +### Opening a memory card + +When launched, all versions of MyMC will prompt you to select a memory card. Browse your computer to find the memory card file you want to modify. + +If you do not know where to find your memory cards, you can use `Tools > Open Data Directory` or `Settings > Memory Cards > Browse` in PCSX2 to quickly jump to the folder which contains them. The default folder name is `memcards`, and your individual memory card files will have `.ps2` file extensions. + + + +After opening, MyMC will populate a table with each game entry in your memory card. Some games which use multiple directory entries will show up as multiple rows; this is the same as how these games will show multiple files when viewed in your PS2 BIOS. + + + +### Adding save files + +To import a save file, click the button which shows an arrow pointing into a memory card. A browser window will pop open and have you navigate to the save file you wish to add. The browser will be filtered to only supported file types such as `.max` (Action Replay Max) and `.cbs` (Code Breaker) among others. Select your save file to import. Once you confirm the selection in the browser, the save file is immediately added to the memory card; you do not need to save the memory card. + +:::info +If your save file is not showing, you can try to switch the filter from Supported Types to All Files. However, if you select an unsupported file type, it will produce an error. +::: + +### Removing save files + +You can remove a save file from your memory card by selecting it in the table, then hitting `File > Delete`. + +:::warning +This action is permanent and applies immediately. It cannot be undone. +::: + +### Exporting save files + +You can export a save file to `.psu` or `.max` formats. The use of this function is to make a copy of your save file separate from your memory card, which you or someone else could then import into another memory card. Select the save file you wish to export in the table, then hit the icon with an arrow leaving the memory card. You will be prompted to give a name to the exported file. + +:::info +Exporting does not remove the save file from your memory card. +::: diff --git a/docs/setup/bios.md b/docs/setup/bios.md index 5e9177a..571019d 100644 --- a/docs/setup/bios.md +++ b/docs/setup/bios.md @@ -1,6 +1,5 @@ --- title: "Dumping BIOS" -date: 2024-03-20 summary: "Steps on how to gather required files for you to be able to use PCSX2" draft: false toc: true diff --git a/docs/setup/dumping.md b/docs/setup/dumping.md index da5b0af..7c76fcd 100644 --- a/docs/setup/dumping.md +++ b/docs/setup/dumping.md @@ -1,6 +1,5 @@ --- title: "Dumping Discs" -date: 2024-03-20 summary: "Steps on how to dump your PS2 discs" draft: false toc: true diff --git a/docs/setup/linux.md b/docs/setup/linux.md index e06d34a..8b61d67 100644 --- a/docs/setup/linux.md +++ b/docs/setup/linux.md @@ -1,6 +1,5 @@ --- title: "Linux Setup" -date: 2024-03-20 summary: "Steps on how to install and run PCSX2 on Linux" draft: false toc: true @@ -59,5 +58,5 @@ The Flatpak is also available for [direct download](https://pcsx2.net/downloads) ## Build from source (Advanced users) :::tip -For details on building PCSX2 from source, check out our [GitHub Wiki](https://github.com/PCSX2/pcsx2/wiki/10-Building-on-Linux). +For details on building PCSX2 from source, check out the [Building PCSX2 page](../advanced/building.md#building-on-linux) ::: diff --git a/docs/setup/requirements.md b/docs/setup/requirements.md index d3b3a97..2d408df 100644 --- a/docs/setup/requirements.md +++ b/docs/setup/requirements.md @@ -1,6 +1,5 @@ --- title: "Requirements" -date: 2024-03-20 summary: "System requirements to get PCSX2 up and running." draft: false toc: true diff --git a/docs/setup/windows.md b/docs/setup/windows.md index a3e84d0..bd2f562 100644 --- a/docs/setup/windows.md +++ b/docs/setup/windows.md @@ -1,6 +1,5 @@ --- title: "Windows Setup" -date: 2024-03-20 summary: "Steps on how to install and run PCSX2 on Windows" draft: false toc: true @@ -54,5 +53,5 @@ Make sure to install all the required software first before proceeding with the ## Build from source (Advanced users) :::tip -For details on building PCSX2 from source, check out our [GitHub Wiki](https://github.com/PCSX2/pcsx2/wiki/12-Building-on-Windows). +For details on building PCSX2 from source, check out the [Building PCSX2 page](../advanced/building.md#building-on-windows) ::: diff --git a/docs/troubleshooting/general.md b/docs/troubleshooting/general.md index f7f6095..c8f52b9 100644 --- a/docs/troubleshooting/general.md +++ b/docs/troubleshooting/general.md @@ -1,6 +1,5 @@ --- title: "General Issues" -date: 2024-03-20 summary: "Common issues that may occur when using PCSX2." draft: false toc: true @@ -46,7 +45,8 @@ If you are using a distro which is not based on Ubuntu, it is recommended that y If your game is not working or you are still having issues, there are a few things you can do: +- Check the [Reporting for issues](./identify.md) page to find out how to report for issues. - Check the [compatibility page](/compat) to see if the game has been tested to run properly. - Consult the [wiki page](https://wiki.pcsx2.net) for the game for similar information. -- Check the [GitHub issues page](https://github.com/PCSX2/pcsx2/issues) to see if there are any reported issues. - Join our [Discord server](https://discord.com/invite/TCz3t9k) for futher assistance. +- Check the [GitHub issues page](https://github.com/PCSX2/pcsx2/issues) to see if there are any reported issues. diff --git a/docs/troubleshooting/identify.md b/docs/troubleshooting/identify.md index 97ae960..12da471 100644 --- a/docs/troubleshooting/identify.md +++ b/docs/troubleshooting/identify.md @@ -1,10 +1,9 @@ --- title: "Reporting for issues" -date: 2024-03-20 summary: "Steps on how to diagnose problems during PCSX2 Setup" draft: false toc: true -sidebar_position: 5 +sidebar_position: 3 --- Hit a snag? Follow through this page to find out on how to gather more information about the issues! Especially useful for when you wanted to report them. @@ -73,4 +72,20 @@ It helps to write down the PCSX2 versions you're testing as you go, and note whe ## Reach out for help -After you've collected all the report materials, consider reaching out in either the respective [Discord](https://www.pcsx2.net/discord) channel or the [forum](https://forums.pcsx2.net/) for further assistance. +After you've collected all the report materials, consider reaching out in either the respective [Discord](https://www.pcsx2.net/discord) channel, the [public forum](https://forums.pcsx2.net/) or our [issue tracker](https://github.com/PCSX2/pcsx2/issues) for further assistance. + +## Commenting Etiquette + +GitHub allows users to comment nearly everywhere. You can comment on issues, on commits, or even on one concrete line of a commit. This is a very powerful tool, but also has a great potential for abuse. + +### Keeping it real + +The comment system is not a forum, and is generally _**not**_ for idle chat. Many of the devs have comments feeding directly into our inboxes, and a bunch of spam for smileys or statements like "make it faster plz" isn't what we consider a good time. So please be considerate. + +There are a few rules an guidelines that we all need to follow in order for this public feedback system to work: + +- Comments should be relevant to the commit/issue and should contain _useful information_. +- If you're having general problems with PCSX2, you can use our [Issue tracker](https://github.com/PCSX2/pcsx2/issues), or if you don't really know what revision causes it, our [Public Forum](https://forums.pcsx2.net). This way we can discuss and troubleshoot the issue in depth, in its right place. +- Statements like "please make it faster" or "please fix my game" are not acceptable and will be deleted. +- Phrasing the statement as a question like "Will this make it faster?" or "Will this fix my game?" is not acceptable either, and will also be deleted. +- If we delete your post, there was a good reason for it. Deleting posts without justification would be counter-productive, much the same way that allowing posts with no relevant content would also be counter-productive. diff --git a/docs/troubleshooting/img/OSD.webp b/docs/troubleshooting/img/OSD.webp index ac1518b..3b91982 100644 Binary files a/docs/troubleshooting/img/OSD.webp and b/docs/troubleshooting/img/OSD.webp differ diff --git a/docs/troubleshooting/img/OSD_HW.webp b/docs/troubleshooting/img/OSD_HW.webp index 4e10901..81ef938 100644 Binary files a/docs/troubleshooting/img/OSD_HW.webp and b/docs/troubleshooting/img/OSD_HW.webp differ diff --git a/docs/troubleshooting/img/OSD_SW.webp b/docs/troubleshooting/img/OSD_SW.webp index edc0e51..834d9b0 100644 Binary files a/docs/troubleshooting/img/OSD_SW.webp and b/docs/troubleshooting/img/OSD_SW.webp differ diff --git a/docs/troubleshooting/img/OSD_Settings.webp b/docs/troubleshooting/img/OSD_Settings.webp index f4d6609..956e8b8 100644 Binary files a/docs/troubleshooting/img/OSD_Settings.webp and b/docs/troubleshooting/img/OSD_Settings.webp differ diff --git a/docs/troubleshooting/linux.md b/docs/troubleshooting/linux.md index bb2d64d..69aa08f 100644 --- a/docs/troubleshooting/linux.md +++ b/docs/troubleshooting/linux.md @@ -1,10 +1,9 @@ --- title: "Linux" -date: 2024-03-20 summary: "Known Linux-specific issues for PCSX2" draft: false toc: true -sidebar_position: 4 +sidebar_position: 5 --- Here are some known Linux-specific issue that can occur. @@ -24,3 +23,7 @@ Then you need to install `libfuse2` in order to the run the AppImage in your env ```bash sudo apt install libfuse2 ``` + +:::tip +This is no longer relevant since PCSX2 v2.1.72 we've now switched to `go-appimage` which supports `libfuse3`. +::: diff --git a/docs/troubleshooting/performance.md b/docs/troubleshooting/performance.md index 709b17b..e72f2b4 100644 --- a/docs/troubleshooting/performance.md +++ b/docs/troubleshooting/performance.md @@ -1,6 +1,5 @@ --- title: "Performance Issues" -date: 2024-03-20 summary: "Steps on how to diagnose performance bottlenecks in PCSX2" draft: false toc: true @@ -119,6 +118,7 @@ CS = EE Cycle Skip FCDVD = Fast CDVD Enabled IVU = Instant VU1 Enabled MTVU = Multi-Threaded VU1 Enabled +VSYNC = VSync EER = EE FPU Rounding Mode EEC = EE FPU Clamping Mode VUR = VU Rounding Mode @@ -129,18 +129,37 @@ IR = Upscale Multiplier/Internal Resolution B = Accurate Blending Unit PL = Texture Preloading PT = GPU Palette Conversion +DL = Hardware Download Mode MM = Hardware Mipmapping BF = Bilinear Filtering TF = Trilinear Filtering AF = Anisotropic Filtering DI = Dithering -CRC = CRC Fix Level -HBO = Half-Bottom Override HPO = Half-Pixel Offset RS = Round Sprite +NS = Native Scaling TCO = Texture Offsets CSBW = CPU Sprite Render BW +CCLUT = Software CLUT Render +GCLUT = GPU Target CLUT SD = Skip Draw +TexRT = Texture Inside RT (Render Target) +BLU = Bilinear Dirty Upscale +FESP = Force Even Sprite Position +NPD = Native Palette Draw +MS = Merge Sprite +AS = Align Sprite +ATFL = Auto Flush +FBC = Framebuffer Conversion +FTC = Read Targets When Closing +DDC = Disable Depth Conversion +DPIV = Disable Partial Source Invalidation +DSF = Disable Safe Features +DRF = Disable Render Fixes +PLFD = Preload Frame Data +ETR = Estimate Texture Region +RBSG = Spin GPU During Readbacks +RBSC = Spin CPU During Readbacks ``` ## Consistently low or unstable FPS diff --git a/docs/troubleshooting/windows.md b/docs/troubleshooting/windows.md index 217cecf..402f39f 100644 --- a/docs/troubleshooting/windows.md +++ b/docs/troubleshooting/windows.md @@ -1,10 +1,9 @@ --- title: "Windows" -date: 2024-03-20 summary: "Known Windows-specific issues for PCSX2" draft: false toc: true -sidebar_position: 3 +sidebar_position: 4 --- Here are some known Windows-specific issue that can occur.