# Technical Documentation: PCSX2/pcsx2 > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/PCSX2/pcsx2) ### Overview (`README.md`) # PCSX2 [](https://app.codacy.com/gh/PCSX2/pcsx2/dashboard?utm_source=github.com&utm_medium=referral&utm_content=PCSX2/pcsx2&utm_campaign=Badge_Grade) [](https://discord.com/invite/TCz3t9k) PCSX2 is a free and open-source PlayStation 2 (PS2) emulator. Its purpose is to emulate the PS2's hardware, using a combination of MIPS CPU [Interpreters](), [Recompilers](https://en.wikipedia.org/wiki/Dynamic_recompilation) and a [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine) which manages hardware states and PS2 system memory. This allows you to play PS2 games on your PC, with many additional features and benefits. ## Project Details PCSX2 has been in development for more than 20 years. Past versions could only run a few public domain game demos, but newer versions can run most games at full speed, including popular titles such as Final Fantasy X and Devil May Cry 3. Visit the [PCSX2 compatibility list](https://pcsx2.net/compat/) to check the latest compatibility status of games (with more than 2500 titles tested). Installers and binaries for both stable and nightly builds are available from [our website](https://pcsx2.net/downloads/). ## System Requirements PCSX2 supports Windows, Linux, and Mac platforms. Our [setup documentation page](https://pcsx2.net/docs/setup/requirements) contains additional details on software and hardware requirements. Please note that a BIOS dump from a legitimately-owned PS2 console is required to use the emulator. For more information, visit [this page](https://pcsx2.net/docs/setup/bios/). ## Contributing / Building PCSX2 supports translation into other languages using [Crowdin](https://crowdin.com/project/pcsx2-emulator). See the [Contribution Guide](https://pcsx2.net/docs/contributing/) for more info on how to contribute. --- ### Overview (`3rdparty/ccc/README.md`) # Chaos Compiler Collection This code was originally developed in the following repository and was copied into PCSX2 by the author: - [https://github.com/chaoticgd/ccc](https://github.com/chaoticgd/ccc) It includes additional resources that are not present in the PCSX2 repository. ## Documentation ### DWARF (.debug) Section - [DWARF Debugging Information Format](https://dwarfstd.org/doc/dwarf_1_1_0.pdf) ### MIPS Debug (.mdebug) Section - [Third Eye Software and the MIPS symbol table (Peter Rowell)](http://datahedron.com/mips.html) - [MIPS Mdebug Debugging Information (David Anderson, 1996)](https://www.prevanders.net/Mdebug.ps) - MIPS Assembly Language Programmer's Guide, Symbol Table Chapter (Silicon Graphics, 1992) - Tru64 UNIX Object File and Symbol Table Format Specification, Symbol Table Chapter - `mdebugread.c` from gdb (reading) - `ecoff.c` from gas (writing) - `include/coff/sym.h` from binutils (headers) ### MIPS EABI - [MIPS EABI](https://sourceware.org/legacy-ml/binutils/2003-06/msg00436.html) ### STABS - [The "stabs" representation of debugging information (Julia Menapace, Jim Kingdon, and David MacKenzie, 1992-???)](https://sourceware.org/gdb/onlinedocs/stabs.html) - `stabs.c` from binutils (reading) - `stabsread.c` from gdb (reading) - `dbxread.c` from gdb (reading) - `dbxout.c` from gcc (writing) - `stab.def` from gcc (symbol codes) --- ### Overview (`3rdparty/cpuinfo/README.md`) # CPU INFOrmation library [](https://github.com/pytorch/cpuinfo/blob/master/LICENSE) [](https://travis-ci.org/pytorch/cpuinfo) [](https://ci.appveyor.com/project/MaratDukhan/cpuinfo/branch/master) cpuinfo is a library to detect essential for performance optimization information about host CPU. ## Features - **Cross-platform** availability: - Linux, Windows, macOS, Android, iOS and FreeBSD operating systems - x86, x86-64, ARM, and ARM64 architectures - Modern **C/C++ interface** - Thread-safe - No memory allocation after initialization - No exceptions thrown - Detection of **supported instruction sets**, up to AVX512 (x86) and ARMv8.3 extensions - Detection of SoC and core information: - **Processor (SoC) name** - Vendor and **microarchitecture** for each CPU core - ID (**MIDR** on ARM, **CPUID** leaf 1 EAX value on x86) for each CPU core - Detection of **cache information**: - Cache type (instruction/data/unified), size and line size - Cache associativity - Cores and logical processors (hyper-threads) sharing the cache - Detection of **topology information** (relative between logical processors, cores, and processor packages) - Well-tested **production-quality** code: - 60+ mock tests based on data from real devices - Includes work-arounds for common bugs in hardware and OS kernels - Supports systems with heterogenous cores, such as **big.LITTLE** and Max.Med.Min - Permissive **open-source** license (Simplified BSD) ## Examples Log processor name: ```c cpuinfo_initialize(); printf("Running on %s CPU\n", cpuinfo_get_package(0)->name); ``` Detect if target is a 32-bit or 64-bit ARM system: ```c #if CPUINFO_ARCH_ARM || CPUINFO_ARCH_ARM64 /* 32-bit ARM-specific code here */ #endif ``` Check if the host CPU supports ARM NEON ```c cpuinfo_initialize(); if (cpuinfo_has_arm_neon()) { neon_implementation(arguments); } ``` Check if the host CPU supports x86 AVX ```c cpuinfo_initialize(); if (cpuinfo_has_x86_avx()) { avx_implementation(arguments); } ``` Check if the thread runs on a Cortex-A53 core ```c cpuinfo_initialize(); switch (cpuinfo_get_current_core()->uarch) { case cpuinfo_uarch_cortex_a53: cortex_a53_implementation(arguments); break; default: generic_implementation(arguments); break; } ``` Get the size of level 1 data cache on the fastest core in the processor (e.g. big core in big.LITTLE ARM systems): ```c cpuinfo_initialize(); const size_t l1_size = cpuinfo_get_processor(0)->cache.l1d->size; ``` Pin thread to cores sharing L2 cache with the current core (Linux or Android) ```c cpuinfo_initialize(); cpu_set_t cpu_set; CPU_ZERO(&cpu_set); const struct cpuinfo_cache* current_l2 = cpuinfo_get_current_processor()->cache.l2; for (uint32_t i = 0; i < current_l2->processor_count; i++) { CPU_SET(cpuinfo_get_processor(current_l2->processor_start + i)->linux_id, &cpu_set); } pthread_setaffinity_np(pthread_self(), sizeof(cpu_set_t), &cpu_set); ``` ## Use via pkg-config If you would like to provide your project's build environment with the necessary compiler and linker flags in a portable manner, the library by default when built enables `CPUINFO_BUILD_PKG_CONFIG` and will generate a [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) manifest (_libcpuinfo.pc_). Here are several examples of how to use it: ### Command Line If you used your distro's package manager to install the library, you can verify that it is available to your build environment like so: ```console $ pkg-config --cflags --libs libcpuinfo -I/usr/include/x86_64-linux-gnu/ -L/lib/x86_64-linux-gnu/ -lcpuinfo ``` If you have installed the library from source into a non-standard prefix, pkg-config may need help finding it: ```console $ PKG_CONFIG_PATH="/home/me/projects/cpuinfo/prefix/lib/pkgconfig/:$PKG_CONFIG_PATH" pkg-config --cflags --libs libcpuinfo -I/home/me/projects/cpuinfo/prefix/include -L/home/me/projects/cpuinfo/prefix/lib -lcpuinfo ``` ### GNU Autotools To [use](https://autotools.io/pkgconfig/pkg_check_modules.html) with the GNU Autotools include the following snippet in your project's `configure.ac`: ```makefile # CPU INFOrmation library... PKG_CHECK_MODULES( [libcpuinfo], [libcpuinfo], [], [AC_MSG_ERROR([libcpuinfo missing...])]) YOURPROJECT_CXXFLAGS="$YOURPROJECT_CXXFLAGS $libcpuinfo_CFLAGS" YOURPROJECT_LIBS="$YOURPROJECT_LIBS $libcpuinfo_LIBS" ``` ### Meson To use with Meson you just need to add `dependency('libcpuinfo')` as a dependency for your executable. ```meson project( 'MyCpuInfoProject', 'cpp', meson_version: '>=0.55.0' ) executable( 'MyCpuInfoExecutable', sources: 'main.cpp', dependencies: dependency('libcpuinfo') ) ``` ### Bazel This project can be built using [Bazel](https://bazel.build/install). You can also use this library as a dependency to your Bazel project. Add to your `MODULE.bazel` file: ```python # fetch cpuinfo from Bazel Central Registry: https://registry.bazel.build/modules/cpuinfo bazel_dep(name = "cpuinfo", version = "0.0.0-20250925-877328f") # Optional: Override it with some specific commit hash git_override( module_name = "cpuinfo", commit = "" remote = "https://github.com/pytorch/cpuinfo.git", ) ``` And to your `BUILD` file: ```python cc_binary( name = "cpuinfo_test", srcs = [ # ... ], deps = [ "@cpuinfo", ], ) ``` ### CMake To use with CMake use the [FindPkgConfig](https://cmake.org/cmake/help/latest/module/FindPkgConfig.html) module. Here is an example: ```cmake cmake_minimum_required(VERSION 3.6) project("MyCpuInfoProject") find_package(PkgConfig) pkg_check_modules(CpuInfo REQUIRED IMPORTED_TARGET libcpuinfo) add_executable(${PROJECT_NAME} main.cpp) target_link_libraries(${PROJECT_NAME} PkgConfig::CpuInfo) ``` ### Makefile To use within a vanilla makefile, you can call pkg-config directly to supply compiler and linker flags using shell substitution. ```makefile CFLAGS=-g3 -Wall -Wextra -Werror ... LDFLAGS=-lfoo ... ... CFLAGS+= $(pkg-config --cflags libcpuinfo) LDFLAGS+= $(pkg-config --libs libcpuinfo) ``` ## Exposed information - [x] Processor (SoC) name - [x] Microarchitecture - [x] Usable instruction sets - [ ] CPU frequency - [x] Cache - [x] Size - [x] Associativity - [x] Line size - [x] Number of partitions - [x] Flags (unified, inclusive, complex hash function) - [x] Topology (logical processors that share this cache level) - [ ] TLB - [ ] Number of entries - [ ] Associativity - [ ] Covered page types (instruction, data) - [ ] Covered page sizes - [x] Topology information - [x] Logical processors - [x] Cores - [x] Packages (sockets) ## Supported environments: - [x] Android - [x] x86 ABI - [x] x86_64 ABI - [x] armeabi ABI - [x] armeabiv7-a ABI - [x] arm64-v8a ABI - [ ] ~~mips ABI~~ - [ ] ~~mips64 ABI~~ - [x] Linux - [x] x86 - [x] x86-64 - [x] 32-bit ARM (ARMv5T and later) - [x] ARM64 - [ ] PowerPC64 - [x] iOS - [x] x86 (iPhone simulator) - [x] x86-64 (iPhone simulator) - [x] ARMv7 - [x] ARM64 - [x] macOS - [x] x86 - [x] x86-64 - [x] ARM64 (Apple silicon) - [x] Windows - [x] x86 - [x] x86-64 - [x] arm64 - [x] FreeBSD - [x] x86-64 ## Methods - Processor (SoC) name detection - [x] Using CPUID leaves 0x80000002–0x80000004 on x86/x86-64 - [x] Using `/proc/cpuinfo` on ARM - [x] Using `ro.chipname`, `ro.board.platform`, `ro.product.board`, `ro.mediatek.platform`, `ro.arch` properties (Android) - [ ] Using kernel log (`dmesg`) on ARM Linux - [x] Using Windows registry on ARM64 Windows - Vendor and microarchitecture detection - [x] Intel-designed x86/x86-64 cores (up to Sunny Cove, Goldmont Plus, and Knights Mill) - [x] AMD-designed x86/x86-64 cores (up to Puma/Jaguar and Zen 2) - [ ] VIA-designed x86/x86-64 cores - [ ] Other x86 cores (DM&P, RDC, Transmeta, Cyrix, Rise) - [x] ARM-designed ARM cores (up to Cortex-A55, Cortex-A77, and Neoverse E1/V1/N2/V2) - [x] Qualcomm-designed ARM cores (Scorpion, Krait, and Kryo) - [x] Nvidia-designed ARM cores (Denver and Carmel) - [x] Samsung-designed ARM cores (Exynos) - [x] Intel-designed ARM cores (XScale up to 3rd-gen) - [x] Apple-designed ARM cores (up to Lightning and Thunder) - [x] Cavium-designed ARM cores (ThunderX) - [x] AppliedMicro-designed ARM cores (X-Gene) - Instruction set detection - [x] Using CPUID (x86/x86-64) - [x] Using `/proc/cpuinfo` on 32-bit ARM EABI (Linux) - [x] Using microarchitecture heuristics on (32-bit ARM) - [x] Using `FPSID` and `WCID` registers (32-bit ARM) - [x] Using `getauxval` (Linux/ARM) - [x] Using `/proc/self/auxv` (Android/ARM) - [ ] Using instruction probing on ARM (Linux) - [ ] Using CPUID registers on ARM64 (Linux) - [x] Using IsProcessorFeaturePresent on ARM64 Windows - Cache detection - [x] Using CPUID leaf 0x00000002 (x86/x86-64) - [x] Using CPUID leaf 0x00000004 (non-AMD x86/x86-64) - [ ] Using CPUID leaves 0x80000005-0x80000006 (AMD x86/x86-64) - [x] Using CPUID leaf 0x8000001D (AMD x86/x86-64) - [x] Using `/proc/cpuinfo` (Linux/pre-ARMv7) - [x] Using microarchitecture heuristics (ARM) - [x] Using chipset name (ARM) - [x] Using `sysctlbyname` (Mach) - [x] Using sysfs `typology` directories (ARM/Linux) - [ ] Using sysfs `cache` directories (Linux) - [x] Using `GetLogicalProcessorInformationEx` on ARM64 Windows - TLB detection - [x] Using CPUID leaf 0x00000002 (x86/x86-64) - [ ] Using CPUID leaves 0x80000005-0x80000006 and 0x80000019 (AMD x86/x86-64) - [x] Using microarchitecture heuristics (ARM) - Topology detection - [x] Using CPUID leaf 0x00000001 on x86/x86-64 (legacy APIC ID) - [x] Using CPUID leaf 0x0000000B on x86/x86-64 (Intel APIC ID) - [ ] Using CPUID leaf 0x8000001E on x86/x86-64 (AMD APIC ID) - [x] Using `/proc/cpuinfo` (Linux) - [x] Using `host_info` (Mach) - [x] Using `GetLogicalProcessorInformationEx` (Windows) - [x] Using sysfs (Linux) - [x] Using chipset name (ARM/Linux) --- ### Overview (`3rdparty/cubeb/README.md`) # libcubeb - Cross-platform Audio I/O Library [](https://github.com/mozilla/cubeb/actions/workflows/build.yml) `libcubeb` is a cross-platform C library for high and low-latency audio input/output. It provides a simple, consistent API for audio playback and recording across multiple platforms and audio backends. It is written in C, C++ and Rust, with a C ABI and [Rust](https://github.com/mozilla/cubeb-rs) bindings. While originally written for use in the Firefox Web browser, a number of other software projects have adopted it. ## Features - **Cross-platform support**: Windows, macOS, Linux, Android, and other platforms - **Versatile**: Optimized for low-latency real-time audio applications, or power efficient higher latency playback - **A/V sync**: Latency compensated audio clock reporting for easy audio/video synchronization - **Full-duplex support**: Simultaneous audio input and output, reclocked - **Device enumeration**: Query available audio devices - **Audio processing for speech**: Can use VoiceProcessing IO on recent macOS ## Supported Backends & status | *Backend* | *Support Level* | *Platform version* | *Notes* | |-------------------|-----------------|--------------------|--------------------------------------------------| | PulseAudio (Rust) | Tier-1 | | Main Linux desktop backend | | AudioUnit (Rust) | Tier-1 | | Main macOS backend | | WASAPI | Tier-1 | Windows >= 7 | Main Windows backend | | AAudio | Tier-1 | Android >= 8 | Main Android backend for most devices | | OpenSL | Tier-1 | Android >= 2.3 | Android backend for older devices | | OSS | Tier-2 | | | | sndio | Tier-2 | | | | Sun | Tier-2 | | | | WinMM | Tier-3 | Windows XP | Was Tier-1, Firefox minimum Windows version 7. | | AudioTrack | Tier-3 | Android < 2.3 | Was Tier-1, Firefox minimum Android version 4.1. | | ALSA | Tier-3 | | | | JACK | Tier-3 | | | | KAI | Tier-3 | | | | PulseAudio (C) | Tier-4 | | Was Tier-1, superseded by Rust | | AudioUnit (C++) | Tier-4 | | Was Tier-1, superseded by Rust | Tier-1: Actively maintained. Should have CI coverage. Critical for Firefox. Tier-2: Actively maintained by contributors. CI coverage appreciated. Tier-3: Maintainers/patches accepted. Status unclear. Tier-4: Deprecated, obsolete. Scheduled to be removed. Note that the support level is not a judgement of the relative merits of a backend, only the current state of support, which is informed by Firefox's needs, the responsiveness of a backend's maintainer, and the level of contributions to that backend. ## Building ### Prerequisites - CMake 3.15 or later - Non-ancient MSVC, clang or gcc, for compiling both C and C++ - Platform-specific audio libraries (automatically detected) - Optional but recommended: Rust compiler to compile and link more recent backends for macOS and PulseAudio ### Quick build ```bash git clone https://github.com/mozilla/cubeb.git cd cubeb cmake -B build cmake --build build ``` ### Better build with Rust backends ```bash git clone --recursive https://github.com/mozilla/cubeb.git cd cubeb cmake -B build -DBUILD_RUST_LIBS=ON cmake --build build ``` ### Platform-Specific Notes **Windows**: Supports Visual Studio 2015+ and MinGW-w64. Use `-G "Visual Studio 16 2019"` or `-G "MinGW Makefiles"`. **macOS**: Requires Xcode command line tools. Audio frameworks are automatically linked. **Linux**: Development packages for desired backends: ```bash # Ubuntu/Debian sudo apt-get install libpulse-dev libasound2-dev libjack-dev # Fedora/RHEL sudo dnf install pulseaudio-libs-devel alsa-lib-devel jack-audio-connection-kit-devel ``` **Android**: Use with Android NDK. AAudio requires API level 26+. ## Testing Run the test suite: ```bash cd build ctest ``` Use the interactive test tool: ```bash ./cubeb-test ``` ## License Licensed under an ISC-style license. See [LICENSE](LICENSE) for details. ## Contributing Contributions are welcome! Please see the [contribution guidelines](CONTRIBUTING.md) and check the [issue tracker](https://github.com/mozilla/cubeb/issues). ## Links - [GitHub Repository](https://github.com/mozilla/cubeb) - [API Documentation](https://mozilla.github.io/cubeb/) --- ### Overview (`3rdparty/d3d12memalloc/README.md`) # D3D12 Memory Allocator Easy to integrate memory allocation library for Direct3D 12. **Documentation:** Browse online: [D3D12 Memory Allocator](https://gpuopen-librariesandsdks.github.io/D3D12MemoryAllocator/html/) (generated from Doxygen-style comments in [include/D3D12MemAlloc.h](include/D3D12MemAlloc.h)) **License:** MIT. See [LICENSE.txt](LICENSE.txt) **Changelog:** See [CHANGELOG.md](CHANGELOG.md) **Product page:** [D3D12 Memory Allocator on GPUOpen](https://gpuopen.com/d3d12-memory-allocator/) [](http://isitmaintained.com/project/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator "Average time to resolve an issue") # Problem Memory allocation and resource (buffer and texture) creation in new, explicit graphics APIs (Vulkan® and Direct3D 12) is difficult comparing to older graphics APIs like Direct3D 11 or OpenGL® because it is recommended to allocate bigger blocks of memory and assign parts of them to resources. [Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/) is a library that implements this functionality for Vulkan. It is available online since 2017 and it is successfully used in many software projects, including some AAA game studios. This is an equivalent library for D3D12. # Features This library can help developers to manage memory allocations and resource creation by offering function `Allocator::CreateResource` similar to the standard `ID3D12Device::CreateCommittedResource`. It internally: - Allocates and keeps track of bigger memory heaps, used and unused ranges inside them, finds best matching unused ranges to create new resources there as placed resources. - Automatically respects size and alignment requirements for created resources. - Automatically handles resource heap tier - whether it's `D3D12_RESOURCE_HEAP_TIER_1` that requires to keep certain classes of resources separate or `D3D12_RESOURCE_HEAP_TIER_2` that allows to keep them all together. Additional features: - Well-documented - description of all classes and functions provided, along with chapters that contain general description and example code. - Thread-safety: Library is designed to be used in multithreaded code. - Configuration: Fill optional members of `ALLOCATOR_DESC` structure to provide custom CPU memory allocator and other parameters. - Customization and integration with custom engines: Predefine appropriate macros to provide your own implementation of external facilities used by the library, like assert, mutex, and atomic. - Support for resource aliasing (overlap). - Custom memory pools: Create a pool with desired parameters (e.g. fixed or limited maximum size, custom `D3D12_HEAP_PROPERTIES` and `D3D12_HEAP_FLAGS`) and allocate memory out of it. - Support for GPU Upload Heaps from preview Agility SDK (needs compilation with `D3D12MA_OPTIONS16_SUPPORTED` macro). - Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion. - Defragmentation: Let the library move data around to free some memory blocks and make your allocations better compacted. - Statistics: Obtain brief or detailed statistics about the amount of memory used, unused, number of allocated heaps, number of allocations etc. - globally and per memory heap type. Current memory usage and budget as reported by the system can also be queried. - Debug annotations: Associate custom `void* pPrivateData` and debug `LPCWSTR pName` with each allocation. - JSON dump: Obtain a string in JSON format with detailed map of internal state, including list of allocations, their string names, and gaps between them. - Convert this JSON dump into a picture to visualize your memory. See [tools/GpuMemDumpVis](tools/GpuMemDumpVis/README.md). - Virtual allocator - an API that exposes the core allocation algorithm to be used without allocating real GPU memory, to allocate your own stuff, e.g. sub-allocate pieces of one large buffer. # Prerequisites - Self-contained C++ library in single pair of H + CPP files. No external dependencies other than standard C, C++ library and Windows SDK. Some features of C++14 used. STL containers, C++ exceptions, and RTTI are not used. - Object-oriented interface in a convention similar to D3D12. - Error handling implemented by returning `HRESULT` error codes - same way as in D3D12. - Interface documented using Doxygen-style comments. # Example Basic usage of this library is very simple. Advanced features are optional. After you created global `Allocator` object, a complete code needed to create a texture may look like this: ```cpp D3D12_RESOURCE_DESC resourceDesc = {}; resourceDesc.Dimension = D3D12_RESOURCE_DIMENSION_TEXTURE2D; resourceDesc.Alignment = 0; resourceDesc.Width = 1024; resourceDesc.Height = 1024; resourceDesc.DepthOrArraySize = 1; resourceDesc.MipLevels = 1; resourceDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM; resourceDesc.SampleDesc.Count = 1; resourceDesc.SampleDesc.Quality = 0; resourceDesc.Layout = D3D12_TEXTURE_LAYOUT_UNKNOWN; resourceDesc.Flags = D3D12_RESOURCE_FLAG_NONE; D3D12MA::ALLOCATION_DESC allocDesc = {}; allocDesc.HeapType = D3D12_HEAP_TYPE_DEFAULT; D3D12Resource* resource; D3D12MA::Allocation* allocation; HRESULT hr = allocator->CreateResource( &allocDesc, &resourceDesc, D3D12_RESOURCE_STATE_COPY_DEST, NULL, &allocation, IID_PPV_ARGS(&resource)); ``` With this one function call: 1. `ID3D12Heap` memory block is allocated if needed. 2. An unused region of the memory block is reserved for the allocation. 3. `ID3D12Resource` is created as placed resource, bound to this region. `Allocation` is an object that represents memory assigned to this texture. It can be queried for parameters like offset and size. # Binaries The release comes with precompiled binary executable for "D3D12Sample" application which contains test suite. It is compiled using Visual Studio 2022, so it requires appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If its launch fails with error message telling about those files missing, please download and install [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170), "X64" version. # Copyright notice This software package uses third party software: - Parts of the code of [Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/) by AMD, license: MIT - Parts of the code of [DirectX-Graphics-Samples](https://github.com/microsoft/DirectX-Graphics-Samples) by Microsoft, license: MIT For more information see [NOTICES.txt](NOTICES.txt). # See also - **[Vcpkg](https://github.com/Microsoft/vcpkg)** dependency manager from Microsoft offers a port of this library that is easy to install. - **[d3d12ma.c](https://github.com/milliewalky/d3d12ma.c)** - C bindings for this library. Author: Mateusz Maciejewski (Matt Walky). License: MIT. - **[TerraFX.Interop.D3D12MemoryAllocator](https://github.com/terrafx/terrafx.interop.d3d12memoryallocator)** - interop bindings for this library for C#, as used by [TerraFX](https://github.com/terrafx/terrafx). License: MIT. - **[Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/)** - equivalent library for Vulkan. License: MIT. # Software using this library - **[Qt Project](https://github.com/qt)** - **[Ghost of Tsushima: Director's Cut PC](https://www.youtube.com/watch?v=cPKBDbCYctc&t=698s)** - Information avaliable in 11:38 of credits - **[Godot Engine](https://github.com/godotengine/godot/)** - multi-platform 2D and 3D game engine. License: MIT. - **[The Forge](https://github.com/ConfettiFX/The-Forge)** - cross-platform rendering framework. Apache License 2.0. - **[Wicked Engine](https://github.com/turanszkij/WickedEngine)** - 3D engine with modern graphics [Some other projects on GitHub](https://github.com/search?q=D3D12MemAlloc.h&type=Code) and some game development studios that use DX12 in their games. --- ### Overview (`3rdparty/fast_float/README.md`) ## fast_float number parsing library: 4x faster than strtod [](https://github.com/fastfloat/fast_float/actions/workflows/ubuntu22.yml) *Note: This library is for C++ users. C programmers should consider [ffc.h](https://github.com/kolemannix/ffc.h). It is a high-performance port of fast_float to C.* The fast_float library provides fast header-only implementations for the C++ from_chars functions for `float` and `double` types as well as integer types. These functions convert ASCII strings representing decimal values (e.g., `1.3e10`) into binary types. We provide exact rounding (including round to even). In our experience, these `fast_float` functions many times faster than comparable number-parsing functions from existing C++ standard libraries. Specifically, `fast_float` provides the following two functions to parse floating-point numbers with a C++17-like syntax (the library itself only requires C++11): ```C++ from_chars_result from_chars(char const *first, char const *last, float &value, ...); from_chars_result from_chars(char const *first, char const *last, double &value, ...); ``` If they are available on your system, we also support fixed-width floating-point types such as `std::float64_t`, `std::float32_t`, `std::float16_t`, and `std::bfloat16_t`. You can also parse integer types such as `char`, `short`, `long`, `long long`, `unsigned char`, `unsigned short`, `unsigned long`, `unsigned long long`, `bool` (0/1), `int8_t`, `int16_t`, `int32_t`, `int64_t`, `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`. ```C++ from_chars_result from_chars(char const *first, char const *last, int &value, ...); from_chars_result from_chars(char const *first, char const *last, unsigned &value, ...); ``` The return type (`from_chars_result`) is defined as the struct: ```C++ struct from_chars_result { char const *ptr; std::errc ec; }; ``` It parses the character sequence `[first, last)` for a number. It parses floating-point numbers expecting a locale-independent format equivalent to the C++17 from_chars function. The resulting floating-point value is the closest floating-point values (using either `float` or `double`), using the "round to even" convention for values that would otherwise fall right in-between two values. That is, we provide exact parsing according to the IEEE standard. Given a successful parse, the pointer (`ptr`) in the returned value is set to point right after the parsed number, and the `value` referenced is set to the parsed value. In case of error, the returned `ec` contains a representative error, otherwise the default (`std::errc()`) value is stored. The implementation does not throw and does not allocate memory (e.g., with `new` or `malloc`). It will parse infinity and nan values. Example: ```C++ #include "fast_float/fast_float.h" #include #include int main() { std::string input = "3.1416 xyz "; double result; auto answer = fast_float::from_chars(input.data(), input.data() + input.size(), result); if (answer.ec != std::errc()) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; } ``` Prior to C++26, checking for a successful `std::from_chars` conversion requires comparing the `from_chars_result::ec` member to `std::errc()`. As an extension `fast_float::from_chars` supports the improved C++26 API that allows checking the result by converting it to `bool`, like so: ```cpp #include "fast_float/fast_float.h" #include #include int main() { std::string input = "3.1416 xyz "; double result; if(auto answer = fast_float::from_chars(input.data(), input.data() + input.size(), result)) { std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; } std::cerr << "failed to parse " << input << std::endl; return EXIT_FAILURE; } ``` You can parse delimited numbers: ```C++ std::string input = "234532.3426362,7869234.9823,324562.645"; double result; auto answer = fast_float::from_chars(input.data(), input.data() + input.size(), result); if (answer.ec != std::errc()) { // check error } // we have result == 234532.3426362. if (answer.ptr[0] != ',') { // unexpected delimiter } answer = fast_float::from_chars(answer.ptr + 1, input.data() + input.size(), result); if (answer.ec != std::errc()) { // check error } // we have result == 7869234.9823. if (answer.ptr[0] != ',') { // unexpected delimiter } answer = fast_float::from_chars(answer.ptr + 1, input.data() + input.size(), result); if (answer.ec != std::errc()) { // check error } // we have result == 324562.645. ``` Like the C++17 standard, the `fast_float::from_chars` functions take an optional last argument of the type `fast_float::chars_format`. It is a bitset value: we check whether `fmt & fast_float::chars_format::fixed` and `fmt & fast_float::chars_format::scientific` are set to determine whether we allow the fixed point and scientific notation respectively. The default is `fast_float::chars_format::general` which allows both `fixed` and `scientific`. The library seeks to follow the C++17 (see [28.2.3.(6.1)](https://eel.is/c++draft/charconv.from.chars#6.1)) specification. * The `from_chars` function does not skip leading white-space characters (unless `fast_float::chars_format::skip_white_space` is set). * [A leading `+` sign](https://en.cppreference.com/w/cpp/utility/from_chars) is forbidden (unless `fast_float::chars_format::allow_leading_plus` is set). * It is generally impossible to represent a decimal value exactly as binary floating-point number (`float` and `double` types). We seek the nearest value. We round to an even mantissa when we are in-between two binary floating-point numbers. Furthermore, we have the following restrictions: * We support `float` and `double`, but not `long double`. We also support fixed-width floating-point types such as `std::float64_t`, `std::float32_t`, `std::float16_t`, and `std::bfloat16_t`. * We only support the decimal format: we do not support hexadecimal strings. * For values that are very large positives or negatives (e.g., `1e9999`), we represent them using a positive or negative infinity and the returned `ec` is set to `std::errc::result_out_of_range`. * For values that are very close to zero (e.g., `1e-9999`), we represent them using a positive or negative zero and the returned `ec` is set to `std::errc::result_out_of_range`. We support Visual Studio, macOS, Linux, freeBSD. We support big and little endian. We support 32-bit and 64-bit systems. We assume that the rounding mode is set to nearest (`std::fegetround() == FE_TONEAREST`). ## Integer types You can also parse integer types using different bases (e.g., 2, 10, 16). The following code will print the number 22250738585072012 three times: ```C++ #include "fast_float/fast_float.h" #include int main() { uint64_t i; std::string str = "22250738585072012"; auto answer = fast_float::from_chars(str.data(), str.data() + str.size(), i); if (answer.ec != std::errc()) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << i << std::endl; std::string binstr = "1001111000011001110110111001001010110100111000110001100"; answer = fast_float::from_chars(binstr.data(), binstr.data() + binstr.size(), i, 2); if (answer.ec != std::errc()) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << i << std::endl; std::string hexstr = "4f0cedc95a718c"; answer = fast_float::from_chars(hexstr.data(), hexstr.data() + hexstr.size(), i, 16); if (answer.ec != std::errc()) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << i << std::endl; return EXIT_SUCCESS; } ``` ## Behavior of result_out_of_range When parsing floating-point values, the numbers can sometimes be too small (e.g., `1e-1000`) or too large (e.g., `1e1000`). The C language established the precedent that these small values are out of range. In such cases, it is customary to parse small values to zero and large values to infinity. That is the behaviour of the C language (e.g., `stdtod`). That is the behaviour followed by the fast_float library. Specifically, we follow Jonathan Wakely's interpretation of the standard: > In any case, the resulting value is one of at most two floating-point values > closest to the value of the string matching the pattern. It is also the approach taken by the [Microsoft C++ library](https://github.com/microsoft/STL/blob/62205ab155d093e71dd9588a78f02c5396c3c14b/tests/std/tests/P0067R5_charconv/test.cpp#L943-L946). Hence, we have the following examples: ```cpp double result = -1; std::string str = "3e-1000"; auto r = fast_float::from_chars(str.data(), str.data() + str.size(), result); // r.ec == std::errc::result_out_of_range // r.ptr == str.data() + 7 // result == 0 ``` ```cpp double result = -1; std::string str = "3e1000"; auto r = fast_float::from_chars(str.data(), str.data() + str.size(), result); // r.ec == std::errc::result_out_of_range // r.ptr == str.data() + 6 // result == std::numeric_limits::infinity() ``` Users who wish for the value to be left unmodified given `std::errc::result_out_of_range` may do so by adding two lines of code: ```cpp double old_result = result; // make copy auto r = fast_float::from_chars(start, end, result); if (r.ec == std::errc::result_out_of_range) { result = old_result; } ``` ## C++20: compile-time evaluation (constexpr) In C++20, you may use `fast_float::from_chars` to parse strings at compile-time, as in the following example: ```C++ // consteval forces compile-time evaluation of the function in C++20. consteval double parse(std::string_view input) { double result; auto answer = fast_float::from_chars(input.data(), input.data() + input.size(), result); if (answer.ec != std::errc()) { return -1.0; } return result; } // This function should compile to a function which // merely returns 3.1415. constexpr double constexptest() { return parse("3.1415 input"); } ``` ## C++23: Fixed width floating-point types The library also supports fixed-width floating-point types such as `std::float64_t`, `std::float32_t`, `std::float16_t`, and `std::bfloat16_t`. E.g., you can write: ```C++ std::float32_t result; auto answer = fast_float::from_chars(f.data(), f.data() + f.size(), result); ``` ## Non-ASCII Inputs We also support UTF-16 and UTF-32 inputs, as well as ASCII/UTF-8, as in the following example: ```C++ #include "fast_float/fast_float.h" #include int main() { std::u16string input = u"3.1416 xyz "; double result; auto answer = fast_float::from_chars(input.data(), input.data() + input.size(), result); if (answer.ec != std::errc()) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; } ``` ## Advanced options: using commas as decimal separator, JSON and Fortran The C++ standard stipulate that `from_chars` has to be locale-independent. In particular, the decimal separator has to be the period (`.`). However, some users still want to use the `fast_float` library with in a locale-dependent manner. Using a separate function called `from_chars_advanced`, we allow the users to pass a `parse_options` instance which contains a custom decimal separator (e.g., the comma). You may use it as follows. ```C++ #include "fast_float/fast_float.h" #include int main() { std::string input = "3,1416 xyz "; double result; fast_float::parse_options options{fast_float::chars_format::general, ','}; auto answer = fast_float::from_chars_advanced(input.data(), input.data() + input.size(), result, options); if ((answer.ec != std::errc()) || ((result != 3.1416))) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; } ``` ### You can also parse Fortran-like inputs ```C++ #include "fast_float/fast_float.h" #include int main() { std::string input = "1d+4"; double result; fast_float::parse_options options{fast_float::chars_format::fortran}; auto answer = fast_float::from_chars_advanced(input.data(), input.data() + input.size(), result, options); if ((answer.ec != std::errc()) || ((result != 10000))) { std::cerr << "parsing failure\n"; return EXIT_FAILURE; } std::cout << "parsed the number " << result << std::endl; return EXIT_SUCCESS; } ``` ### You may also enforce the JSON format ([RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259#section-6)) ```C++ #include "fast_float/fast_float.h" #include int main() { std::string input = "+.1"; // not valid double result; fast_float::parse_options options{fast_float::chars_format::json}; auto answer = fast_float::from_chars_advanced(input.data(), input.data() + input.size(), result, options); if (answer.ec == std::errc()) { std::cerr << "should have failed\n"; return EXIT_FAILURE; } return EXIT_SUCCESS; } ``` By default the JSON format does not allow `inf`: ```C++ #include "fast_float/fast_float.h" #include int main() { std::string input = "inf"; // not valid in JSON double result; fast_float::parse_options options{fast_float::chars_format::json}; auto answer = fast_float::from_chars_advanced(input.data(), input.data() + input.size(), result, options); if (answer.ec == std::errc()) { std::cerr << "should have failed\n"; return EXIT_FAILURE; } return EXIT_SUCCESS; } ``` You can allow it with a non-standard `json_or_infnan` variant: ```C++ #include "fast_float/fast_float.h" #include int main() { std::string input = "inf"; // not valid in JSON but we allow it with json_or_infnan double result; fast_float::parse_options options{fast_float::chars_format::json_or_infnan}; auto answer = fast_float::from_chars_advanced(input.data(), input.data() + input.size(), result, options); if (answer.ec != std::errc() || (!std::isinf(result))) { std::cerr << "should have parsed infinity\n"; return EXIT_FAILURE; } return EXIT_SUCCESS; } ``` ## Multiplication of an integer by a power of 10 An integer `W` can be multiplied by a power of ten `10^Q` and converted to `double` with correctly rounded value (in "round to nearest, tie to even" fashion) using `fast_float::integer_times_pow10()`, e.g.: ```C++ const uint64_t W = 12345678901234567; const int Q = 23; const double result = fast_float::integer_times_pow10(W, Q); std::cout.precision(17); std::cout << W << " * 10^" << Q << " = " << result << " (" << (result == 12345678901234567e23 ? "==" : "!=") << "expected)\n"; ``` outputs ``` 12345678901234567 * 10^23 = 1.2345678901234567e+39 (==expected) ``` `fast_float::integer_times_pow10()` gives the same result as using `fast_float::from_chars()` when parsing the string `"WeQ"` (in this example `"12345678901234567e23"`), except `fast_float::integer_times_pow10()` does not report out-of-range errors, and underflows to zero or overflows to infinity when the resulting value is out of range. You can use template overloads to get the result converted to different supported floating-point types: `float`, `double`, etc. For example, to get result as `float` use `fast_float::integer_times_pow10()` specialization: ```C++ const uint64_t W = 12345678; const int Q = 23; const float result = fast_float::integer_times_pow10(W, Q); std::cout.precision(9); std::cout << "float: " << W << " * 10^" << Q << " = " << result << " (" << (result == 12345678e23f ? "==" : "!=") << "expected)\n"; ``` outputs ``` float: 12345678 * 10^23 = 1.23456782e+30 (==expected) ``` Overloads of `fast_float::integer_times_pow10()` are provided for signed and unsigned integer types: `int64_t`, `uint64_t`, etc. ## Users and Related Work The fast_float library is part of: * GCC (as of version 12): the `from_chars` function in GCC relies on fast_float, * [Chromium](https://github.com/Chromium/Chromium), the engine behind Google Chrome, Microsoft Edge, and Opera, * Boost JSON, MySQL, etc. * Blender * [WebKit](https://github.com/WebKit/WebKit), the engine behind Safari (Apple's web browser), * [DuckDB](https://duckdb.org), * [Redis](https://github.com/redis/redis) and [Valkey](https://github.com/valkey-io/valkey), * [Apache Arrow](https://github.com/apache/arrow/pull/8494) where it multiplied the number parsing speed by two or three times, * [Google Jsonnet](https://github.com/google/jsonnet), * [ClickHouse](https://github.com/ClickHouse/ClickHouse). The fastfloat algorithm is part of the [LLVM standard libraries](https://github.com/llvm/llvm-project/commit/87c016078ad72c46505461e4ff8bfa04819fe7ba). There is a [derived implementation part of AdaCore](https://github.com/AdaCore/VSS). The [SerenityOS operating system](https://github.com/SerenityOS/serenity/commit/53b7f5e6a11e663c83df8030c3171c5945cb75ec) has a derived implementation that is inherited by the [Ladybird Browser](https://github.com/LadybirdBrowser/ladybird). The fast_float library provides a performance similar to that of the [fast_double_parser](https://github.com/lemire/fast_double_parser) library but using an updated algorithm reworked from the ground up, and while offering an API more in line with the expectations of C++ programmers. The fast_double_parser library is part of the [Microsoft LightGBM machine-learning framework](https://github.com/microsoft/LightGBM). Packages ------ [](https://repology.org/project/fast-float/versions) ## References * Daniel Lemire, [Number Parsing at a Gigabyte per Second](https://arxiv.org/abs/2101.11408), Software: Practice and Experience 51 (8), 2021. * Noble Mushtak, Daniel Lemire, [Fast Number Parsing Without Fallback](https://arxiv.org/abs/2212.06644), Software: Practice and Experience 53 (7), 2023. ## Other programming languages * [There is an R binding](https://github.com/eddelbuettel/rcppfastfloat) called `rcppfastfloat`. * [There is a Rust port of the fast_float library](https://github.com/aldanor/fast-float-rust/) called `fast-float-rust`. * [There is a Java port of the fast_float library](https://github.com/wrandelshofer/FastDoubleParser) called `FastDoubleParser`. It used for important systems such as [Jackson](https://github.com/FasterXML/jackson-core). * [There is a C# port of the fast_float library](https://github.com/CarlVerret/csFastFloat) called `csFastFloat`. * [There is a plain C port of the fast_float library](https://github.com/kolemannix/ffc.h) called ffc.h ## How fast is it? It can parse random floating-point numbers at a speed of 1 GB/s on some systems. We find that it is often twice as fast as the best available competitor, and many times faster than many standard-library implementations. fast_float is many times faster than many standard-library implementations ```bash $ ./build/benchmarks/benchmark # parsing random integers in the range [0,1) volume = 2.09808 MB netlib : 271.18 MB/s (+/- 1.2 %) 12.93 Mfloat/s doubleconversion : 225.35 MB/s (+/- 1.2 %) 10.74 Mfloat/s strtod : 190.94 MB/s (+/- 1.6 %) 9.10 Mfloat/s abseil : 430.45 MB/s (+/- 2.2 %) 20.52 Mfloat/s fastfloat : 1042.38 MB/s (+/- 9.9 %) 49.68 Mfloat/s ``` See the [Benchmarking](#benchmarking) section for instructions on how to run our benchmarks. ## Video [](https://www.youtube.com/watch?v=AVXgvlMeIm4) ## Using as a CMake dependency This library is header-only by design. The CMake file provides the `fast_float` target which is merely a pointer to the `include` directory. If you drop the `fast_float` repository in your CMake project, you should be able to use it in this manner: ```cmake add_subdirectory(fast_float) target_link_libraries(myprogram PUBLIC fast_float) ``` Or you may want to retrieve the dependency automatically if you have a sufficiently recent version of CMake (3.11 or better at least): ```cmake FetchContent_Declare( fast_float GIT_REPOSITORY https://github.com/fastfloat/fast_float.git GIT_TAG tags/v8.2.5 GIT_SHALLOW TRUE) FetchContent_MakeAvailable(fast_float) target_link_libraries(myprogram PUBLIC fast_float) ``` You should change the `GIT_TAG` line so that you recover the version you wish to use. You may also use [CPM](https://github.com/cpm-cmake/CPM.cmake), like so: ```cmake CPMAddPackage( NAME fast_float GITHUB_REPOSITORY "fastfloat/fast_float" GIT_TAG v8.2.5) ``` ## Using as single header The script `script/amalgamate.py` may be used to generate a single header version of the library if so desired. Just run the script from the root directory of this repository. You can customize the license type and output file if desired as described in the command line help. You may directly download automatically generated single-header files: ## Benchmarking The project has its own benchmarks with realistic data inputs. Under Linux or macOS, you can use it as follows if your system supports C++17: ``` cmake -B build -D FASTFLOAT_BENCHMARKS=ON cmake --build build ./build/benchmarks/realbenchmark ``` Importantly, by default, the benchmark is built in Release mode. The instructions are similar under Windows. Under Linux and macOS, it is recommended to run the benchmarks in a privileged manner to get access to hardware performance counters. You may be able to do so with the `sudo` command in some cases: ``` sudo ./build/benchmarks/realbenchmark ``` If you have a text file containing one number per line (`myfile.txt`), you can run a benchmark over it like so: ``` cmake -B build -D FASTFLOAT_BENCHMARKS=ON cmake --build build ./build/benchmarks/realbenchmark myfile.txt ``` ## Packages * The fast_float library is part of the [Conan package manager](https://conan.io/center/recipes/fast_float). * It is part of the [brew package manager](https://formulae.brew.sh/formula/fast_float). * fast_float is available on [xmake](https://xmake.io) repository. * Some Linux distribution like Fedora include fast_float (e.g., as `fast_float-devel`). ## Credit Though this work is inspired by many different people, this work benefited especially from exchanges with Michael Eisel, who motivated the original research with his key insights, and with Nigel Tao who provided invaluable feedback. Rémy Oudompheng first implemented a fast path we use in the case of long digits. The library includes code adapted from Google Wuffs (written by Nigel Tao) which was originally published under the Apache 2.0 license. ## Stars [](https://www.star-history.com/#fastfloat/fast_float&Date) ## License Licensed under either of Apache License, Version 2.0 or MIT license or BOOST license.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this repository by you, as defined in the Apache-2.0 license, shall be triple licensed as above, without any additional terms or conditions. --- ### Overview (`3rdparty/fmt/README.md`) {fmt} []( https://github.com/fmtlib/fmt/actions?query=workflow%3Alinux) []( https://github.com/fmtlib/fmt/actions?query=workflow%3Amacos) []( https://github.com/fmtlib/fmt/actions?query=workflow%3Awindows) []( https://issues.oss-fuzz.com/issues?q=title:fmt%20cc:victor.zverovich@gmail.com) []( https://www.bestpractices.dev/projects/8880) []( https://securityscorecards.dev/viewer/?uri=github.com/fmtlib/fmt) [![Ask questions at StackOverflow with the tag fmt]( https://img.shields.io/badge/stackoverflow-fmt-blue.svg)](https://stackoverflow.com/questions/tagged/fmt) [![Support Ukraine]( https://img.shields.io/badge/Support-Ukraine-005BBB?labelColor=FFD500)](https://novaukraine.org/) **{fmt}** is an open-source formatting library providing a fast and safe alternative to C stdio and C++ iostreams. [Documentation](https://fmt.dev) [Cheat Sheets](https://hackingcpp.com/cpp/libs/fmt.html) Q&A: ask questions on [StackOverflow with the tag fmt](https://stackoverflow.com/questions/tagged/fmt). Try {fmt} in [Compiler Explorer](https://godbolt.org/z/8Mx1EW73v). # Features - Simple [format API](https://fmt.dev/latest/api/) with positional arguments for localization - Implementation of [C++20 std::format](https://en.cppreference.com/w/cpp/utility/format) and [C++23 std::print](https://en.cppreference.com/w/cpp/io/print) - [Format string syntax](https://fmt.dev/latest/syntax/) similar to Python\'s [format](https://docs.python.org/3/library/stdtypes.html#str.format) - Fast IEEE 754 floating-point formatter with correct rounding, shortness and round-trip guarantees using the [Dragonbox](https://github.com/jk-jeon/dragonbox) algorithm - Portable Unicode support - Safe [printf implementation](https://fmt.dev/latest/api/#printf-api) including the POSIX extension for positional arguments - Extensibility: [support for user-defined types](https://fmt.dev/latest/api/#formatting-user-defined-types) - High performance: faster than common standard library implementations of `(s)printf`, iostreams, `to_string` and `to_chars`, see [Speed tests](#speed-tests) and [Converting a hundred million integers to strings per second](http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html) - Small code size both in terms of source code with the minimum configuration consisting of just three files, `base.h`, `format.h` and `format-inl.h`, and compiled code; see [Compile time and code bloat](#compile-time-and-code-bloat) - Reliability: the library has an extensive set of [tests](https://github.com/fmtlib/fmt/tree/master/test) and is [continuously fuzzed](https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dfmt&can=1) - Safety: the library is fully type-safe, errors in format strings can be reported at compile time, automatic memory management prevents buffer overflow errors - Ease of use: small self-contained code base, no external dependencies, permissive MIT [license](https://github.com/fmtlib/fmt/blob/master/LICENSE) - [Portability](https://fmt.dev/latest/#portability) with consistent output across platforms and support for older compilers - Clean warning-free codebase even on high warning levels such as `-Wall -Wextra -pedantic` - Locale independence by default - Optional header-only configuration enabled with the `FMT_HEADER_ONLY` macro See the [documentation](https://fmt.dev) for more details. # Examples **Print to stdout** ([run](https://godbolt.org/z/Tevcjh)) ``` c++ #include int main() { fmt::print("Hello, world!\n"); } ``` **Format a string** ([run](https://godbolt.org/z/oK8h33)) ``` c++ std::string s = fmt::format("The answer is {}.", 42); // s == "The answer is 42." ``` **Format a string using positional arguments** ([run](https://godbolt.org/z/Yn7Txe)) ``` c++ std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy"); // s == "I'd rather be happy than right." ``` **Print dates and times** ([run](https://godbolt.org/z/c31ExdY3W)) ``` c++ #include int main() { auto now = std::chrono::system_clock::now(); fmt::print("Date and time: {}\n", now); fmt::print("Time: {:%H:%M}\n", now); } ``` Output: Date and time: 2023-12-26 19:10:31.557195597 Time: 19:10 **Print a container** ([run](https://godbolt.org/z/MxM1YqjE7)) ``` c++ #include #include int main() { std::vector v = {1, 2, 3}; fmt::print("{}\n", v); } ``` Output: [1, 2, 3] **Check a format string at compile time** ``` c++ std::string s = fmt::format("{:d}", "I am not a number"); ``` This gives a compile-time error in C++20 because `d` is an invalid format specifier for a string. **Write a file from a single thread** ``` c++ #include int main() { auto out = fmt::output_file("guide.txt"); out.print("Don't {}", "Panic"); } ``` This can be [up to 9 times faster than `fprintf`]( http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html). **Print with colors and text styles** ``` c++ #include int main() { fmt::print(fg(fmt::color::crimson) | fmt::emphasis::bold, "Hello, {}!\n", "world"); fmt::print(fg(fmt::color::floral_white) | bg(fmt::color::slate_gray) | fmt::emphasis::underline, "Olá, {}!\n", "Mundo"); fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic, "你好{}！\n", "世界"); } ``` Output on a modern terminal with Unicode support: # Benchmarks ## Speed tests | Library | Method | Run Time, s | |-------------------|---------------|-------------| | libc | printf | 0.66 | | libc++ | std::ostream | 1.63 | | {fmt} 12.1 | fmt::print | 0.44 | | Boost Format 1.88 | boost::format | 3.89 | | Folly Format | folly::format | 1.28 | {fmt} is the fastest of the benchmarked methods, \~50% faster than `printf`. The above results were generated by building `tinyformat_test.cpp` on macOS 15.6.1 with `clang++ -O3 -DNDEBUG -DSPEED_TEST -DHAVE_FORMAT`, and taking the best of three runs. In the test, the format string `"%0.10f:%04d:%+g:%s:%p:%c:%%\n"` or equivalent is filled 2,000,000 times with output sent to `/dev/null`; for further details refer to the [source](https://github.com/fmtlib/format-benchmark/blob/master/src/tinyformat-test.cc). {fmt} is up to 20-30x faster than `std::ostringstream` and `sprintf` on IEEE754 `float` and `double` formatting ([dtoa-benchmark](https://github.com/fmtlib/dtoa-benchmark)) and faster than [double-conversion](https://github.com/google/double-conversion) and [ryu](https://github.com/ulfjack/ryu): [](https://fmt.dev/unknown_mac64_clang12.0.html) ## Compile time and code bloat The script [bloat-test.py][test] from [format-benchmark][bench] tests compile time and code bloat for nontrivial projects. It generates 100 translation units and uses `printf()` or its alternative five times in each to simulate a medium-sized project. The resulting executable size and compile time (Apple clang version 15.0.0 (clang-1500.1.0.2.5), macOS Sonoma, best of three) is shown in the following tables. [test]: https://github.com/fmtlib/format-benchmark/blob/master/bloat-test.py [bench]: https://github.com/fmtlib/format-benchmark **Optimized build (-O3)** | Method | Compile Time, s | Executable size, KiB | Stripped size, KiB | |-----------------|-----------------|----------------------|--------------------| | printf | 1.6 | 54 | 50 | | IOStreams | 28.4 | 98 | 84 | | {fmt} `1122268` | 5.0 | 54 | 50 | | tinyformat | 32.6 | 164 | 136 | | Boost Format | 55.0 | 530 | 317 | {fmt} is fast to compile and is comparable to `printf` in terms of per-call binary size (within a rounding error on this system). **Non-optimized build** | Method | Compile Time, s | Executable size, KiB | Stripped size, KiB | |-----------------|-----------------|----------------------|--------------------| | printf | 1.4 | 54 | 50 | | IOStreams | 27.0 | 88 | 68 | | {fmt} `1122268` | 4.7 | 87 | 84 | | tinyformat | 28.1 | 185 | 145 | | Boost Format | 38.9 | 678 | 381 | `libc`, `lib(std)c++`, and `libfmt` are all linked as shared libraries to compare formatting function overhead only. Boost Format is a header-only library so it doesn\'t provide any linkage options. ## Running the tests Please refer to [Building the library](https://fmt.dev/latest/get-started/#building-from-source) for instructions on how to build the library and run the unit tests. Benchmarks reside in a separate repository, [format-benchmarks](https://github.com/fmtlib/format-benchmark), so to run the benchmarks you first need to clone this repository and generate Makefiles with CMake: $ git clone --recursive https://github.com/fmtlib/format-benchmark.git $ cd format-benchmark $ cmake . Then you can run the speed test: $ make speed-test or the bloat test: $ make bloat-test # Migrating code [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) v18 provides the [modernize-use-std-print](https://clang.llvm.org/extra/clang-tidy/checks/modernize/use-std-print.html) check that is capable of converting occurrences of `printf` and `fprintf` to `fmt::print` if configured to do so. (By default it converts to `std::print`.) # Notable projects using this library - [0 A.D.](https://play0ad.com/): a free, open-source, cross-platform real-time strategy game - [AMPL/MP](https://github.com/ampl/mp): an open-source library for mathematical programming - [Apple's FoundationDB](https://github.com/apple/foundationdb): an open-source, distributed, transactional key-value store - [Aseprite](https://github.com/aseprite/aseprite): animated sprite editor & pixel art tool - [AvioBook](https://www.aviobook.aero/en): a comprehensive aircraft operations suite - [Blizzard Battle.net](https://battle.net/): an online gaming platform - [Celestia](https://celestia.space/): real-time 3D visualization of space - [Ceph](https://ceph.com/): a scalable distributed storage system - [ccache](https://ccache.dev/): a compiler cache - [ClickHouse](https://github.com/ClickHouse/ClickHouse): an analytical database management system - [ContextVision](https://www.contextvision.com/): medical imaging software - [Contour](https://github.com/contour-terminal/contour/): a modern terminal emulator - [CUAUV](https://cuauv.org/): Cornell University\'s autonomous underwater vehicle - [Drake](https://drake.mit.edu/): a planning, control, and analysis toolbox for nonlinear dynamical systems (MIT) - [Envoy](https://github.com/envoyproxy/envoy): C++ L7 proxy and communication bus (Lyft) - [FiveM](https://fivem.net/): a modification framework for GTA V - [fmtlog](https://github.com/MengRao/fmtlog): a performant fmtlib-style logging library with latency in nanoseconds - [Folly](https://github.com/facebook/folly): Facebook open-source library - [GemRB](https://gemrb.org/): a portable open-source implementation of Bioware's Infinity Engine - [Grand Mountain Adventure](https://store.steampowered.com/app/1247360/Grand_Mountain_Adventure/): a beautiful open-world ski & snowboarding game - [HarpyWar/pvpgn](https://github.com/pvpgn/pvpgn-server): Player vs Player Gaming Network with tweaks - [KBEngine](https://github.com/kbengine/kbengine): an open-source MMOG server engine - [Keypirinha](https://keypirinha.com/): a semantic launcher for Windows - [Kodi](https://kodi.tv/) (formerly xbmc): home theater software - [Knuth](https://kth.cash/): high-performance Bitcoin full-node - [libunicode](https://github.com/contour-terminal/libunicode/): a modern C++17 Unicode library - [MariaDB](https://mariadb.org/): relational database management system - [Microsoft Verona](https://github.com/microsoft/verona): research programming language for concurrent ownership - [MongoDB](https://mongodb.com/): distributed document database - [MongoDB Smasher](https://github.com/duckie/mongo_smasher): a small tool to generate randomized datasets - [OpenSpace](https://openspaceproject.com/): an open-source astrovisualization framework - [PenUltima Online (POL)](https://www.polserver.com/): an MMO server, compatible with most Ultima Online clients - [PyTorch](https://github.com/pytorch/pytorch): an open-source machine learning library - [quasardb](https://www.quasardb.net/): a distributed, high-performance, associative database - [Quill](https://github.com/odygrd/quill): asynchronous low-latency logging library - [QKW](https://github.com/ravijanjam/qkw): generalizing aliasing to simplify navigation, and execute complex multi-line terminal command sequences - [redis-cerberus](https://github.com/HunanTV/redis-cerberus): a Redis cluster proxy - [redpanda](https://vectorized.io/redpanda): a 10x faster Kafka® replacement for mission-critical systems written in C++ - [rpclib](http://rpclib.net/): a modern C++ msgpack-RPC server and client library - [Salesforce Analytics Cloud](https://www.salesforce.com/analytics-cloud/overview/): business intelligence software - [Scylla](https://www.scylladb.com/): a Cassandra-compatible NoSQL data store that can handle 1 million transactions per second on a single server - [Seastar](http://www.seastar-project.org/): an advanced, open-source C++ framework for high-performance server applications on modern hardware - [spdlog](https://github.com/gabime/spdlog): super fast C++ logging library - [Stellar](https://www.stellar.org/): financial platform - [Touch Surgery](https://www.touchsurgery.com/): surgery simulator - [TrinityCore](https://github.com/TrinityCore/TrinityCore): open-source MMORPG framework - [🐙 userver framework](https://userver.tech/): open-source asynchronous framework with a rich set of abstractions and database drivers - [Windows Terminal](https://github.com/microsoft/terminal): the new Windows terminal [More\...](https://github.com/search?q=fmtlib&type=Code) If you are aware of other projects using this library, please let me know by [email](mailto:victor.zverovich@gmail.com) or by submitting an [issue](https://github.com/fmtlib/fmt/issues). # Maintainers The {fmt} library is maintained by Victor Zverovich ([vitaut](https://github.com/vitaut)) with contributions from many other people. See [Contributors](https://github.com/fmtlib/fmt/graphs/contributors) and [Releases](https://github.com/fmtlib/fmt/releases) for some of the names. Let us know if your contribution is not listed or mentioned incorrectly and we\'ll make it right. --- ### Overview (`3rdparty/googletest/README.md`) # GoogleTest ### Announcements #### Documentation Updates Our documentation is now live on GitHub Pages at https://google.github.io/googletest/. We recommend browsing the documentation on GitHub Pages rather than directly in the repository. #### Release 1.18.0 [Release 1.18.0](https://github.com/google/googletest/releases/tag/v1.18.0) is now available. The 1.18.x branch [requires at least C++17](https://opensource.google/documentation/policies/cplusplus-support#c_language_standard). #### Continuous Integration We use Google's internal systems for continuous integration. #### Coming Soon * We are planning to take a dependency on [Abseil](https://github.com/abseil/abseil-cpp). ## Welcome to **GoogleTest**, Google's C++ test framework! This repository is a merger of the formerly separate GoogleTest and GoogleMock projects. These were so closely related that it makes sense to maintain and release them together. ### Getting Started See the [GoogleTest User's Guide](https://google.github.io/googletest/) for documentation. We recommend starting with the [GoogleTest Primer](https://google.github.io/googletest/primer.html). More information about building GoogleTest can be found at [googletest/README.md](googletest/README.md). ## Features * xUnit test framework: \ Googletest is based on the [xUnit](https://en.wikipedia.org/wiki/XUnit) testing framework, a popular architecture for unit testing. * Test discovery: \ Googletest automatically discovers and runs your tests, eliminating the need to manually register your tests. * Rich set of assertions: \ Googletest provides a variety of assertions, such as equality, inequality, exceptions, and more, making it easy to test your code. * User-defined assertions: \ You can define your own assertions with Googletest, making it simple to write tests that are specific to your code. * Death tests: \ Googletest supports death tests, which verify that your code exits in a certain way, making it useful for testing error-handling code. * Fatal and non-fatal failures: \ You can specify whether a test failure should be treated as fatal or non-fatal with Googletest, allowing tests to continue running even if a failure occurs. * Value-parameterized tests: \ Googletest supports value-parameterized tests, which run multiple times with different input values, making it useful for testing functions that take different inputs. * Type-parameterized tests: \ Googletest also supports type-parameterized tests, which run with different data types, making it useful for testing functions that work with different data types. * Various options for running tests: \ Googletest provides many options for running tests including running individual tests, running tests in a specific order and running tests in parallel. ## Supported Platforms GoogleTest follows Google's [Foundational C++ Support Policy](https://opensource.google/documentation/policies/cplusplus-support). See [this table](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md) for a list of currently supported versions of compilers, platforms, and build tools. ## Who Is Using GoogleTest? In addition to many internal projects at Google, GoogleTest is also used by the following notable projects: * The [Chromium projects](https://www.chromium.org/) (behind the Chrome browser and Chrome OS). * The [LLVM](https://llvm.org/) compiler. * [Protocol Buffers](https://github.com/google/protobuf), Google's data interchange format. * The [OpenCV](https://opencv.org/) computer vision library. ## Related Open Source Projects [GTest Runner](https://github.com/nholthaus/gtest-runner) is a Qt5 based automated test-runner and Graphical User Interface with powerful features for Windows and Linux platforms. [GoogleTest UI](https://github.com/ospector/gtest-gbar) is a test runner that runs your test binary, allows you to track its progress via a progress bar, and displays a list of test failures. Clicking on one shows failure text. GoogleTest UI is written in C#. [GTest TAP Listener](https://github.com/kinow/gtest-tap-listener) is an event listener for GoogleTest that implements the [TAP protocol](https://en.wikipedia.org/wiki/Test_Anything_Protocol) for test result output. If your test runner understands TAP, you may find it useful. [gtest-parallel](https://github.com/google/gtest-parallel) is a test runner that runs tests from your binary in parallel to provide significant speed-up. [GoogleTest Adapter](https://marketplace.visualstudio.com/items?itemName=DavidSchuldenfrei.gtest-adapter) is a VS Code extension allowing to view GoogleTest in a tree view and run/debug your tests. [C++ TestMate](https://github.com/matepek/vscode-catch2-test-adapter) is a VS Code extension allowing to view GoogleTest in a tree view and run/debug your tests. [Cornichon](https://pypi.org/project/cornichon/) is a small Gherkin DSL parser that generates stub code for GoogleTest. ## Contributing Changes Please read [`CONTRIBUTING.md`](https://github.com/google/googletest/blob/main/CONTRIBUTING.md) for details on how to contribute to this project. Happy testing! --- ### Overview (`3rdparty/libchdr/README.md`) # libchdr libchdr is a standalone library for reading MAME's CHDv1-v5 formats. The code is based off of MAME's old C codebase which read up to CHDv4 with OS-dependent features removed, and CHDv5 support backported from MAME's current C++ codebase. libchdr is licensed under the BSD 3-Clause (see [LICENSE.txt](LICENSE.txt)) and uses third party libraries that are each distributed under their own terms (see each library's license in [deps/](deps/)). --- ### Overview (`3rdparty/rainterface/README.md`) # RAInterface This code is intended to be loaded into another repository as a submodule. An emulator should include RA_Interface.cpp in its build and link against winhttp.lib. Then, the emulator can be modified to call the hooks provided in RA_Interface.cpp at appropriate times to integrate with the RetroAchievements server via the RA_Integration.dll. See wiki for more details. --- ### Overview (`3rdparty/rcheevos/README.md`) # **rcheevos** **rcheevos** is a set of C code, or a library if you will, that tries to make it easier for emulators to process [RetroAchievements](https://retroachievements.org) data, providing support for achievements and leaderboards for their players. Keep in mind that **rcheevos** does *not* provide HTTP network connections. Clients must get data from RetroAchievements, and pass the response down to **rcheevos** for processing. Not all structures defined by **rcheevos** can be created via the public API, but are exposed to allow interactions beyond just creation, destruction, and testing, such as the ones required by UI code that helps to create them. **NOTE**: development occurs on the _develop_ branch, which is set as the default branch in GitHub so newly opened PRs will request to be merged into the _develop_ branch. When integrating **rcheevos** into your project, we recommend using the _master_ branch, which corresponds to the last official release, and minimizes the risk of encountering a bug that has been introduced since the last official release. ## API An understanding about how achievements are developed may be useful, you can read more about it [here](https://docs.retroachievements.org/developer-docs/). Most of the exposed APIs are documented [here](https://github.com/RetroAchievements/rcheevos/wiki) ### Return values Any function in the rcheevos library that returns a success indicator will return `RC_OK` or one of the constants defined in `rc_error.h`. To convert the return code into something human-readable, pass it to: ```c const char* rc_error_str(int ret); ``` ### Console identifiers Platforms supported by RetroAchievements are enumerated in `rc_consoles.h`. Note that some consoles in the enum are not yet fully supported (may require a memory map or some way to uniquely identify games). ## Runtime support A set of functions for managing an active game is provided by the library. If you are considering adding achievement support to your emulator, you should look at the `rc_client_t` functions which will prepare the API calls and other implement other common functionality (like managing the user information, identifying/loading a game, and building the active/inactive achievements list for the UI). It has several callback functions which allow the client to implement dependent functionality (UI and HTTP calls). Please see [the wiki](https://github.com/RetroAchievements/rcheevos/wiki/rc_client-integration) for details on using the `rc_client_t` functions. ## Server Communication **rapi** builds URLs to access many RetroAchievements web services. Its purpose it to just to free the developer from having to URL-encode parameters and build correct URLs that are valid for the server. **rapi** does *not* make HTTP requests. NOTE: `rc_client` is the preferred way to have a client interact with the server. **rapi** headers are `rc_api_user.h`, `rc_api_runtime.h` and `rc_api_common.h`. The basic process of making an **rapi** call is to initialize a params object, call a function to convert it to a URL, send that to the server, then pass the response to a function to convert it into a response object, and handle the response values. An example can be found on the [rc_api_init_login_request](https://github.com/RetroAchievements/rcheevos/wiki/rc_api_init_login_request#example) page. ### Functions Please see the [wiki](https://github.com/RetroAchievements/rcheevos/wiki) for details on the functions exposed for **rapi**. ## Game Identification **rhash** provides logic for generating a RetroAchievements hash for a given game. There are two ways to use the API - you can pass the filename and let rhash open and process the file, or you can pass the buffered copy of the file to rhash if you've already loaded it into memory. These are in `rc_hash.h`. ```c void rc_hash_initialize_iterator(rc_hash_iterator_t* iterator, const char* path, const uint8_t* buffer, size_t buffer_size); int rc_hash_generate(char hash[33], uint32_t console_id, const rc_hash_iterator_t* iterator); int rc_hash_iterate(char hash[33], rc_hash_iterator_t* iterator); void rc_hash_destroy_iterator(rc_hash_iterator_t* iterator); ``` ### Custom file handling **rhash** (and by extension **rc_client**) support custom handlers for opening/reading files. This allows the client to redirect file reads to support custom file formats (like ZIP or CHD). --- ### Overview (`3rdparty/soundtouch/readme.md`) # SoundTouch library ## About SoundTouch is an open-source audio processing library that allows changing the sound tempo, pitch and playback rate parameters independently from each other: * Change **tempo** while maintaining the original pitch * Change **pitch** while maintaining the original tempo * Change **playback rate** that affects both tempo and pitch at the same time * Change any combination of tempo/pitch/rate Visit [SoundTouch website](https://www.surina.net/soundtouch) and see the [README file](https://www.surina.net/soundtouch/readme.html) for more information and audio examples. ## Version **The latest stable release in Git is 2.4.1** See the [README file for change history](https://soundtouch.surina.net/README.html#changehistory) [](https://repology.org/project/soundtouch/versions) ## Example Use SoundStretch example app for modifying wav audio files, for example as follows: ``` soundstretch my_original_file.wav output_file.wav -tempo=+15 -pitch=-3 ``` See the [README file](https://soundtouch.surina.net/README.html) for more usage examples and instructions how to build the software. Ready [SoundStretch application executables](https://www.surina.net/soundtouch/download.html) are available for download for Windows and Mac OS. ## Language & Platforms SoundTouch is written in C++ and compiles in virtually any platform: * Windows * Mac OS * Linux & Unices (including also Raspberry, Beaglebone, Yocto etc embedded Linux flavors) * Android * iOS * embedded systems The source code package includes dynamic library import modules for C#, Java and Pascal/Delphi languages. ## Tarballs Source code release tarballs: * https://www.surina.net/soundtouch/soundtouch-2.4.1.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.4.0.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.3.3.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.3.2.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.3.1.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.3.0.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.2.0.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.1.2.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.1.1.tar.gz * https://www.surina.net/soundtouch/soundtouch-2.0.0.tar.gz ## License SoundTouch is released under LGPL v2.1: This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 2.1 as published by the Free Software Foundation. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA See [LGPL v2.1 full license text ](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html) for details. -- Also commercial license free of GPL limitations available upon request --- ### Overview (`3rdparty/vixl/README.md`) VIXL: Arm Runtime Code Generation Library ========================================= Contents: * [Overview](#overview) * [Licence](#licence) * [Requirements](#requirements) * [Versioning](#versioning) * [Supported Arm Architecture Features](#supported-arm-architecture-features) * [Known limitations](#known-limitations) * [Bug reports](#bug-reports) * [Usage](#usage) Overview ======== VIXL contains three components. 1. Programmatic **assemblers** to generate A64, A32 or T32 code at runtime. The assemblers abstract some of the constraints of each ISA; for example, some instructions support any immediate. 2. **Disassemblers** that can print any instruction emitted by the assemblers. 3. An **A64 simulator** that can simulate any instruction emitted by the A64 assembler. The simulator allows generated code to be run on another architecture without the need for a full ISA model. The VIXL git repository can be found [on GitLab][vixl]. Build status: [](https://gitlab.arm.com/runtimes/vixl/-/pipelines) Licence ======= This software is covered by the licence described in the [LICENCE](LICENCE) file. Contributions, as pull requests or via other means, are accepted under the terms of the same [LICENCE](LICENCE). Requirements ============ To build VIXL the following software is required: 1. Python 3.5+ 2. SCons 2.0 3. GCC 4.8+ or Clang 4.0+ A 64-bit host machine is required, implementing an LP64 data model. VIXL has been tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu systems. To run the code formatting stages of the tests, the following software is also required: 1. clang-format 11+ 2. clang-tidy 11+ Refer to the 'Usage' section for details. Note that in Ubuntu 18.04, clang-tidy-4.0 will only work if the clang-4.0 package is also installed. Versioning ========== VIXL uses [Semantic Versioning 2.0.0][semver] - see [VERSIONS](VERSIONS.md) for details. Supported Arm Architecture Features =================================== | Feature | VIXL CPUFeatures Flag | Notes | |------------|-------------------------------|---------------------------------| | BTI | kBTI | Per-page enabling not supported | | CSSC | kCSSC | | | DotProd | kDotProduct | | | FCMA | kFcma | | | FHM | kFHM | | | FP16 | kFPHalf, kNEONHalf | | | FRINTTS | kFrintToFixedSizedInt | | | FlagM | kFlagM | | | FlagM2 | kAXFlag | | | I8MM | kI8MM | | | JSCVT | kJSCVT | | | LOR | kLORegions | | | LRCPC | kRCpc | | | LRCPC2 | kRCpcImm | | | LSE | kAtomics | | | MOPS | kMOPS | | | MTE | kMTEInstructions, kMTE, kMTE3 | | | PAuth | kPAuth, kPAuthGeneric | Not ERETAA, ERETAB | | RAS | kRAS | | | RDM | kRDM | | | SVE | kSVE | | | SVE2 | kSVE2 | | | SVEBitPerm | kSVEBitPerm | | | SVEF32MM | kSVEF32MM | | | SVEF64MM | kSVEF64MM | | | SVEI8MM | kSVEI8MM | | Enable generating code for an architecture feature by combining a flag with the MacroAssembler's defaults. For example, to generate code for SVE, use `masm.GetCPUFeatures()->Combine(CPUFeatures::kSVE);`. See [the cpu features header file](src/cpu-features.h) for more information. Known Limitations ================= VIXL was developed for JavaScript engines so a number of features from A64 were deemed unnecessary: * Limited rounding mode support for floating point. * Limited support for synchronisation instructions. * Limited support for system instructions. * A few miscellaneous integer and floating point instructions are missing. The VIXL simulator supports only those instructions that the VIXL assembler can generate. The `doc` directory contains a [list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md). The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it builds and mostly works for 32-bit x86 platforms, there are a number of floating-point operations which do not work correctly, and a number of tests fail as a result. Debug Builds ------------ Your project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`) when using a VIXL library that has been built with debug enabled. Some classes defined in VIXL header files contain fields that are only present in debug builds, so if `VIXL_DEBUG` is defined when the library is built, but not defined for the header files included in your project, you will see runtime failures. Exclusive-Access Instructions ----------------------------- All exclusive-access instructions are supported, but the simulator cannot accurately simulate their behaviour as described in the ARMv8 Architecture Reference Manual. * A local monitor is simulated, so simulated exclusive loads and stores execute as expected in a single-threaded environment. * The global monitor is simulated by occasionally causing exclusive-access instructions to fail regardless of the local monitor state. * Load-acquire, store-release semantics are approximated by issuing a host memory barrier after loads or before stores. The built-in `__sync_synchronize()` is used for this purpose. The simulator tries to be strict, and implements the following restrictions that the ARMv8 ARM allows: * A pair of load-/store-exclusive instructions will only succeed if they have the same address and access size. * Most of the time, cache-maintenance operations or explicit memory accesses will clear the exclusive monitor. * To ensure that simulated code does not depend on this behaviour, the exclusive monitor will sometimes be left intact after these instructions. Instructions affected by these limitations: `stxrb`, `stxrh`, `stxr`, `ldxrb`, `ldxrh`, `ldxr`, `stxp`, `ldxp`, `stlxrb`, `stlxrh`, `stlxr`, `ldaxrb`, `ldaxrh`, `ldaxr`, `stlxp`, `ldaxp`, `stlrb`, `stlrh`, `stlr`, `ldarb`, `ldarh`, `ldar`, `clrex`. Security Considerations ----------------------- VIXL allows callers to generate any code they want. The generated code is arbitrary, and can therefore call back into any other component in the process. As with any self-modifying code, vulnerabilities in the client or in VIXL itself could lead to arbitrary code generation. For performance reasons, VIXL's Assembler only performs debug-mode checking of instruction operands (such as immediate field encodability). This can minimise code-generation overheads for advanced compilers that already model instructions accurately, and might consider the Assembler's checks to be redundant. The Assembler should only be used directly where encodability is independently checked, and where fine control over all generated code is required. The MacroAssembler synthesises multiple-instruction sequences to support _some_ unencodable operand combinations. The MacroAssembler can provide a useful safety check in cases where the Assembler's precision is not required; an unexpected unencodable operand should result in a macro with the correct behaviour, rather than an invalid instruction. In general, the MacroAssembler handles operands which are likely to vary with user-supplied data, but does not usually handle inputs which are likely to be easily covered by tests. For example, move-immediate arguments are likely to be data-dependent, but register types (e.g. `x` vs `w`) are not. We recommend that _all_ users use the MacroAssembler, using `ExactAssemblyScope` to invoke the Assembler when specific instruction sequences are required. This approach is recommended even in cases where a compiler can model the instructions precisely, because, subject to the limitations described above, it offers an additional layer of protection against logic bugs in instruction selection. Bug reports =========== Bug reports may be made in the Issues section of GitLab, or sent to vixl@arm.com. Please provide any steps required to recreate a bug, along with build environment and host system information. Usage ===== Running all Tests ----------------- The helper script `tools/test.py` will build and run every test that is provided with VIXL, in both release and debug mode. It is a useful script for verifying that all of VIXL's dependencies are in place and that VIXL is working as it should. By default, `tools/test.py` tests code formatting using `clang-format-4.0`, and performs static analysis using `clang-tidy-4.0`. If you don't have these tools, disable the test using `--noclang-format` or `--noclang-tidy`, respectively. Also note that the tests for the tracing features depend upon external `diff` and `sed` tools. If these tools are not available in `PATH`, these tests will fail. Getting Started --------------- We have separate guides for introducing VIXL, depending on what architecture you are targeting. A guide for working with AArch32 can be found [here][getting-started-aarch32], while the AArch64 guide is [here][getting-started-aarch64]. Example source code is provided in the [examples](examples) directory. You can build examples with either `scons aarch32_examples` or `scons aarch64_examples` from the root directory, or use `scons --help` to get a detailed list of available build targets. [vixl]: https://gitlab.arm.com/runtimes/vixl "The VIXL repository on GitLab." [semver]: https://semver.org/spec/v2.0.0.html "Semantic Versioning 2.0.0 Specification" [getting-started-aarch32]: doc/aarch32/getting-started-aarch32.md "Introduction to VIXL for AArch32." [getting-started-aarch64]: doc/aarch64/getting-started-aarch64.md "Introduction to VIXL for AArch64." --- ### Overview (`3rdparty/vulkan/README.md`) # Vulkan-Headers Vulkan header files and API registry This repository contains Vulkan header files, include files for C and C++, and related scripts and tests. Most of the files in this repository are sourced from, or generated from, other repositories as described in [CONTRIBUTING.md](CONTRIBUTING.md). Vulkan-Headers exists as a staging area for these files, most of which are then consumed by downstream repositories used to build SDK components such as the Vulkan Validation Layers and Conformance Test Suite. Developers normally obtain headers from the official [Vulkan-SDK](https://www.lunarg.com/vulkan-sdk/). They can also use headers from, or packaged from, this repository. In most cases, developers should only need the headers, not the scripts and other material in this repository. If you need to run the scripts, please use them from their canonical source in the [Vulkan Specification repository](https://github.com/KhronosGroup/Vulkan-Docs). ## Contributing See the [CONTRIBUTING.md](CONTRIBUTING.md) ## Building See [BUILD.md](BUILD.md) ## SDK Support Vulkan-Headers are shipped as part of the official [Vulkan-SDK](https://www.lunarg.com/vulkan-sdk/) ## C/C++ Package Manager Support `Vulkan-Headers` are also supported by both [conan](https://conan.io/) & [vcpkg](https://learn.microsoft.com/en-us/vcpkg/). ## Version Tagging Scheme Updates to this repository which correspond to a new Vulkan specification release are tagged using the following format: `v<`_`version`_`>` (e.g., `v1.3.266`). **Note**: Marked version releases have undergone thorough testing but do not imply the same quality level as SDK tags. SDK tags follow the `vulkan-sdk-<`_`version`_`>.<`_`patch`_`>` format (e.g., `vulkan-sdk-1.3.266.0`). This scheme was adopted following the `1.3.266` Vulkan specification release. --- ### Overview (`3rdparty/winwil/README.md`) # Windows Implementation Libraries (WIL) [](https://dev.azure.com/msft-wil/Windows%20Implementation%20Library/_build/latest?definitionId=1&branchName=master) The Windows Implementation Libraries (WIL) is a header-only C++ library created to make life easier for developers on Windows through readable type-safe C++ interfaces for common Windows coding patterns. Some things that WIL includes to whet your appetite: - [`include/wil/resource.h`](include/wil/resource.h) ([documentation](https://github.com/Microsoft/wil/wiki/RAII-resource-wrappers)): Smart pointers and auto-releasing resource wrappers to let you manage Windows API HANDLEs, HWNDs, and other resources and resource handles with [RAII](https://en.cppreference.com/w/cpp/language/raii) semantics. - [`include/wil/win32_helpers.h`](include/wil/win32_helpers.h) ([documentation](https://github.com/microsoft/wil/wiki/Win32-helpers)): Wrappers for API functions that save you the work of manually specifying buffer sizes, calling a function twice to get the needed buffer size and then allocate and pass the right-size buffer, casting or converting between types, and so on. - [`include/wil/registry.h`](include/wil/registry.h) ([documentation](https://github.com/microsoft/wil/wiki/Registry-Helpers)): Type-safe functions to read from, write to, and watch the registry. Also, registry watchers that can call a lambda function or a callback function you provide whenever a certain tree within the Windows registry changes. - [`include/wil/network.h`](include/wil/network.h): ([documentation](https://github.com/microsoft/wil/wiki/Network-Helpers)) Supports Winsock and network APIs by providing a header-include list which addresses the inter-header include dependendies; provides RAII objects for WSAStartup refcounts as well as the various addrinfo* types returned from the family of getaddrinfo* functions; provides a type-safe class for managing the entire family of sockaddr-related structures. - [`include/wil/result.h`](include/wil/result.h) ([documentation](https://github.com/Microsoft/wil/wiki/Error-handling-helpers)): Preprocessor macros to help you check for errors from Windows API functions, in many of the myriad ways those errors are reported, and surface them as error codes or C++ exceptions in your code. - [`include/wil/Tracelogging.h`](include/wil/Tracelogging.h): This file contains the convenience macros that enable developers define and log telemetry. These macros use [`TraceLogging API`](https://docs.microsoft.com/en-us/windows/win32/tracelogging/trace-logging-portal) to log data. This data can be viewed in tools such as [`Windows Performance Analyzer`](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer). WIL can be used by C++ code that uses C++ exceptions as well as code that uses returned error codes to report errors. All of WIL can be used from user-space Windows code, and some (such as the RAII resource wrappers) can even be used in kernel mode. # Documentation This project is documented in [its GitHub wiki](https://github.com/Microsoft/wil/wiki). Feel free to contribute to it! # Consuming WIL WIL follows the "live at head" philosophy, so you should feel free to consume WIL directly from the GitHub repo however you please: as a GIT submodule, symbolic link, download and copy files, etc. and update to the latest version at your own cadence. Alternatively, WIL is available using a few package managers, mentioned below. These packages will be updated periodically, likely to average around once or twice per month. ## Consuming WIL via NuGet WIL is available on nuget.org under the name [Microsoft.Windows.ImplementationLibrary](https://www.nuget.org/packages/Microsoft.Windows.ImplementationLibrary/). This package includes the header files under the [include](include) directory as well as a [.targets](packaging/nuget/Microsoft.Windows.ImplementationLibrary.targets) file. ## Consuming WIL via vcpkg WIL is also available using [vcpkg](https://github.com/microsoft/vcpkg) under the name [wil](https://github.com/microsoft/vcpkg/blob/master/ports/wil/portfile.cmake). Instructions for installing packages can be found in the [vcpkg GitHub docs](https://github.com/microsoft/vcpkg/blob/master/docs/examples/installing-and-using-packages.md). In general, once vcpkg is set up on the system, you can run: ```cmd C:\vcpkg> vcpkg install wil:x86-windows C:\vcpkg> vcpkg install wil:x64-windows ``` Note that even though WIL is a header-only library, you still need to install the package for all architectures/platforms you wish to use it with. Otherwise, WIL won't be added to the include path for the missing architectures/platforms. Execute `vcpkg help triplet` for a list of available options. # Building/Testing ## Prerequisites To get started contributing to WIL, first make sure that you have: * The latest version of [Visual Studio](https://visualstudio.microsoft.com/downloads/) or Build Tools for Visual Studio with the latest MSVC C++ build tools and Address Sanitizer components included. In Visual Studio Installer's Import Configuration tool, pick [.vsconfig](.vsconfig) to the necessary workloads installed. * The most recent [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk) * [Nuget](https://www.nuget.org/downloads) downloaded and added to `PATH` - see [Install NuGet client tools](https://learn.microsoft.com/nuget/install-nuget-client-tools) * [vcpkg](https://vcpkg.io) available on your system. Follow their [getting started](https://vcpkg.io/en/getting-started) guide to get set up. Make sure the `VCKPKG_ROOT` environment variable is set, and the path to `vcpkg.exe` is in your `%PATH%`. * A recent version of [Clang](http://releases.llvm.org/download.html) You can install these with WinGet in a console command line: ```powershell winget install Microsoft.VisualStudio.2022.Community winget install Microsoft.WindowsSDK.10.0.22621 winget install Microsoft.NuGet -e winget install Kitware.CMake -e winget install Ninja-build.Ninja -e # Select "Add LLVM to the system path for all users" winget install -i llvm.llvm ``` By default, `init.cmd` and `cmake` attempt to find vcpkg's cmake integration toolchain file on their own, by looking in the `VCPKG_ROOT` environment variable. After bootstrapping, you can use `setx` to have this variable across shell sessions. Make sure the directory containing `vcpkg.exe` is in your `PATH`. If `VCPKG_ROOT` is not set you can pass its location to CMake or the `init.cmd` script with one of these: * `cmake [...] --toolchain [path to vcpkg]/scripts/buildsystems/vcpkg.cmake` * `scripts\init.cmd [...] --vcpkg ` Note that if you use the `init.cmd` script (mentioned below), this path can be specified or auto-detected if you: 1. Have the `VCPKG_ROOT` environment variable set to the root of your vcpkg clone. You can use the `setx` command to have this variable persist across shell sessions, 1. Have the path to the root of your vcpkg clone added to your `PATH` (i.e. the path to `vcpkg.exe`), or 1. If your vcpkg clone is located at the root of the same drive as your WIL clone (e.g. `C:\vcpkg` if your WIL clone is on the `C:` drive) ## Visual Studio 2022 Visual Studio 2022 has [fully integrated CMake support](https://learn.microsoft.com/cpp/build/cmake-projects-in-visual-studio). Opening this directory in Visual Studio 2022 uses the default "clang Debug" configurations. Other configurations for "clang Release," "msvc Debug," and "msvc Release" are available in the Configuration drop-down. Use "Build > Build All" to compile all targets. ## Visual Studio Code Microsoft's [CMake Tools for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) make working in VSCode easy. 1. Start a "Native Tools Command Prompt" (see below) 1. Launch VS Code from the prompt, giving it the path to this repo (like `code c:\wil`) 3. Use "CMake: Select Configure Preset" to pick `clang`, then "CMake: Select Build Preset" to pick `clang Debug`, then "CMake: Select Build Target" and pick `all` 4. Use "CMake: Build" to compile all targets ## Command Line Once everything is installed (you'll need to restart Terminal if you updated `PATH` and don't have [this 2023 fix](https://github.com/microsoft/terminal/pull/14999)), open a VS native command window (e.g. `x64 Native Tools Command Prompt for VS 2022` \[_not_ `Developer Command Prompt for VS2022`]). You can use a [CMake preset](./CMakePresets.json) to configure the environment: ```powershell # Configure for clang compiler, then build clang-debug C:\wil> cmake --preset "clang" C:\wil> cmake --build --preset "clang-debug" ``` You can also use [`scripts/init.cmd`](./scripts/init.cmd) to pick the configuration: ```cmd C:\wil> scripts\init.cmd -c clang -g ninja -b debug ``` This script supports using msbuild as the generator/build-tool (pass `-g msbuild`) and the other [`CMAKE_BUILD_TYPE` values](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) (pass `-b minsizerel`). You can execute `init.cmd --help` for a summary of available options. The `scripts/init_all.cmd` script will run the `init.cmd` script for all combinations of Clang/MSVC and Debug/RelWithDebInfo. > **Note**: For either script, projects will only be generated for the architecture of the current VS command window. ## Inner loop In Visual Studio 2022, select a startup item (e.g. `witest.exe`) and use "Debug > Start Debugging". Targets will be rebuilt as needed. Use "Build > Rebuild All" to rebuild all tests. Use the Visual Studio Test Explorer to run the tests. In VS Code, use "CMake: Set Launch/Debug Target" and select a target (e.g. `witest.exe`). Use "CMake: Debug" (default keybind `Shift-F5`) to run the selected test [in VS Code's debugger environment.](https://code.visualstudio.com/docs/cpp/cpp-debug). Switch to [VS Code's "testing" tab,](https://code.visualstudio.com/docs/debugtest/testing) and click the "Run Tests" option. For command-line CMake (configured with `cmake --preset ...`) build use, some examples: ```powershell # Build for MSVC release, all targets C:\wil> cmake --build --preset "msvc-release" # Build only one test (e.g. for improved compile times) C:\wil> cmake --build --preset "msvc-release" --target "witest.noexcept" # Clean outputs, then build one target C:\wil> cmake --build --preset "msvc-release" --clean-first --target "witest" # Run tests C:\wil> ctest --preset "msvc-release" ``` For command-line Ninja (configured with `init.cmd -c clang -b debug`) build use, some examples: ```powershell # Build all tests C:\wil> ninja -C build\clang-x64-debug # Build only one test C:\wil> ninja -C build\clang-x64-debug witest # Clean outputs, then build one target C:\wil> ninja -C build\clang-x64-debug -j 0 clean witest.app # Run the tests (PowerShell) C:\wil> Get-ChildItem -Recurse -File build\clang-x64-debug\witest*.exe | %{ Write-Host $_ ; & $_ } # Run the tests (cmd) C:\wil> for /F %f IN ('dir /s /b build\clang\tests\witest*.exe') do %f ``` The output is a number of test executables. If you used the initialization script(s) mentioned above, or if you followed the same directory naming convention of those scripts, you can use the [runtests.cmd](scripts/runtests.cmd) script, which will execute any test executables that have been built, erroring out - and preserving the exit code - if any test fails. Note that MSBuild will modify the output directory names, so this script is only compatible with using Ninja as the generator. > **Note:** The `witest.app` test is significantly slower than the other tests. You can use Test Explorer or the Testing > tab to hide it while doing quick validation. ## Build everything If you are at the tail end of of a change, you can execute the following to get a wide range of coverage: ```cmd C:\wil> scripts\init_all.cmd C:\wil> scripts\build_all.cmd C:\wil> scripts\runtests.cmd ``` ## Formatting This project has adopted `clang-format` as the tool for formatting our code. Please note that the `.clang-format` at the root of the repo is a copy from the internal Windows repo with few additions. In general, please do not modify it. If you find that a macro is causing bad formatting of code, you can add that macro to one of the corresponding arrays in the `.clang-format` file (e.g. `AttributeMacros`, etc.), format the code, and submit a PR. > _NOTE: Different versions of `clang-format` may format the same code differently. In an attempt to maintain consistency between changes, we've standardized on using the version of `clang-format` that ships with the latest version of Visual Studio. If you have LLVM installed and added to your `PATH`, the version of `clang-format` that gets picked up by default may not be the one we expect. If you leverage the formatting scripts we have provided in the `scripts` directory, these should automatically pick up the proper version provided you are using a Visual Studio command window._ Before submitting a PR to the WIL repo we ask that you first run `clang-format` on your changes. There is a CI check in place that will fail the build for your PR if you have not run `clang-format`. There are a few different ways to format your code: ### 1. Formatting with `git clang-format` > **Important!** Git integration with `clang-format` is only available through the LLVM distribution. You can install LLVM through their [GibHub releases page](https://github.com/llvm/llvm-project/releases), via `winget install llvm.llvm`, or through the package manager of your choice. > **Important!** The use of `git clang-format` additionally requires Python to be installed and available on your `PATH`. The simplest way to format just your changes is to use `clang-format`'s `git` integration. You have the option to do this continuously as you make changes, or at the very end when you're ready to submit a PR. To format code continuously as you make changes, you run `git clang-format` after staging your changes. For example: ```cmd C:\wil> git add * C:\wil> git clang-format --style file ``` At this point, the formatted changes will be unstaged. You can review them, stage them, and then commit. Please note that this will use whichever version of `clang-format` is configured to run with this command. You can pass `--binary ` to specify the path to `clang-format.exe` you would like the command to use. If you'd like to format changes at the end of development, you can run `git clang-format` against a specific commit/label. The simplest is to run against `upstream/master` or `origin/master` depending on whether or not you are developing in a fork. Please note that you likely want to sync/merge with the master branch prior to doing this step. You can leverage the `format-changes.cmd` script we provide, which will use the version of `clang-format` that ships with Visual Studio: ```cmd C:\wil> git fetch upstream C:\wil> git merge upstream/master C:\wil> scripts\format-changes.cmd upstream/master ``` ### 2. Formatting with `clang-format` > **Important!** The path to `clang-format.exe` is not added to `PATH` automatically, even when using a Visual Studio command window. The LLVM installer has the option to add itself to the system or user `PATH` if you'd like. If you would like the path to the version of `clang-format` that ships with Visual Studio added to your path, you will need to do so manually. Otherwise, the `run-clang-format.cmd` script mentioned below (or, equivalently, building the `format` target) will manually invoke the `clang-format.exe` under your Visual Studio install path. An alternative, and generally easier option, is to run `clang-format` either on all source files or on all source files you've modified. Note, however, that depending on how `clang-format` is invoked, the version used may not be the one that ships with Visual Studio. Some tools such as Visual Studio Code allow you to specify the path to the version of `clang-format` that you wish to use when formatting code, however this is not always the case. The `run-clang-format.cmd` script we provide will ensure that the version of `clang-format` used is the version that shipped with your Visual Studio install: ```cmd C:\wil> scripts\run-clang-format.cmd ``` Additionally, we've added a build target that will invoke this script, named `format`: ```cmd C:\wil\build\clang-x64-debug> ninja format ``` Please note that this all assumes that your Visual Studio installation is up to date. If it's out of date, code unrelated to your changes may get formatted unexpectedly. If that's the case, you may need to manually revert some modifications that are unrelated to your changes. > _NOTE: Occasionally, Visual Studio will update without us knowing and the version installed for you may be newer than the version installed the last time we ran the format all script. If that's the case, please let us know so that we can re-format the code._ # Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com. When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. --- ### Overview (`3rdparty/zydis/README.md`)

zydis logo

License: MIT GitHub Actions Fuzzing Status Discord

Fast and lightweight x86/x86-64 disassembler and code generation library.

## Features - Supports all x86 and x86-64 (AMD64) instructions and [extensions](./include/Zydis/Generated/EnumISAExt.h) - Optimized for high performance - No dynamic memory allocation ("malloc") - Thread-safe by design - Very small file-size overhead compared to other common disassembler libraries - [Complete doxygen documentation](https://doc.zydis.re/) - Trusted by many major open-source projects - Examples include [x64dbg][zydis-x64dbg], [Mozilla Firefox][zydis-firefox] and [Webkit][zydis-webkit] - Absolutely no third party dependencies — not even libc - Should compile on any platform with a working C11 compiler - Tested on Windows, macOS, FreeBSD, Linux and UEFI, both user and kernel mode [zydis-x64dbg]: https://github.com/x64dbg/x64dbg/tree/729285ef82580812edf7167c41aa6a2c23d8d72d/src/zydis_wrapper [zydis-firefox]: https://github.com/mozilla/gecko-dev/tree/3ddbce3c426a55080bd84974444f9ac4869e580b/js/src/zydis [zydis-webkit]: https://github.com/WebKit/WebKit/tree/1f2d2a92eeb831bedd01bbb5b694a0e29fa9af81/Source/JavaScriptCore/disassembler/zydis ## Examples ### Disassembler The following example program uses Zydis to disassemble a given memory buffer and prints the output to the console. https://github.com/zyantific/zydis/blob/214536a814ba20d2e33d2a907198d1a329aac45c/examples/DisassembleSimple.c#L38-L63 The above example program generates the following output: ```asm 007FFFFFFF400000 push rcx 007FFFFFFF400001 lea eax, [rbp-0x01] 007FFFFFFF400004 push rax 007FFFFFFF400005 push qword ptr [rbp+0x0C] 007FFFFFFF400008 push qword ptr [rbp+0x08] 007FFFFFFF40000B call [0x008000007588A5B1] 007FFFFFFF400011 test eax, eax 007FFFFFFF400013 js 0x007FFFFFFF42DB15 ``` ### Encoder https://github.com/zyantific/zydis/blob/b37076e69f5aa149fde540cae43c50f15a380dfc/examples/EncodeMov.c#L39-L62 The above example program generates the following output: ``` 48 C7 C0 37 13 00 00 ``` ### More Examples More examples can be found in the [examples](./examples/) directory of this repository. ## Build There are many ways to make Zydis available on your system. The following sub-sections list commonly used options. ### CMake Build **Platforms:** Windows, macOS, Linux, BSDs You can use CMake to build Zydis on all supported platforms. Instructions on how to install CMake can be found [here](https://cmake.org/install/). ```bash git clone --recursive 'https://github.com/zyantific/zydis.git' cd zydis cmake -B build cmake --build build -j4 ``` ### Visual Studio 2022 project **Platforms:** Windows We manually maintain a [Visual Studio 2022 project](./msvc/) in addition to the CMake build logic. ### CMake generated VS project **Platforms:** Windows CMake can be instructed to generate a Visual Studio project for pretty much any VS version. A video guide describing how to use the CMake GUI to generate such project files is available [here](https://www.youtube.com/watch?v=fywLDK1OAtQ). Don't be confused by the apparent use of macOS in the video: Windows is simply running in a virtual machine. ### Amalgamated distribution **Platforms:** any platform with a working C11 compiler We provide an auto-generated single header & single source file variant of Zydis. To use this variant of Zydis in your project, all you need to do is to copy these two files into your project. The amalgamated builds can be found on our [release page](https://github.com/zyantific/zydis/releases) as `zydis-amalgamated.tar.gz`. These files are generated with the [`amalgamate.py`](./assets/amalgamate.py) script. ### Package managers **Platforms:** Windows, macOS, Linux, FreeBSD Pre-built headers, shared libraries and executables are available through a variety of package managers.
Zydis version in various package repositories [](https://repology.org/project/zydis/versions)
| Repository | Install command | |------------|--------------------------------------------| | Arch Linux | `pacman -S zydis` | | Debian | `apt-get install libzydis-dev zydis-tools` | | Homebrew | `brew install zydis` | | NixOS | `nix-shell -p zydis` | | Ubuntu | `apt-get install libzydis-dev zydis-tools` | | vcpkg | `vcpkg install zydis` | ## Using Zydis in a CMake project An example on how to use Zydis in your own CMake based project [can be found in this repo](https://github.com/zyantific/zydis-submodule-example). ## `ZydisInfo` tool The `ZydisInfo` command-line tool can be used to inspect essentially all information that Zydis provides about an instruction. ## Bindings Official bindings exist for a selection of languages: - [Rust](https://github.com/zyantific/zydis-rs) - [Python 3](https://github.com/zyantific/zydis-py) ### asmjit-style C++ front-end If you're looking for an asmjit-style assembler front-end for the encoder, check out [zasm](https://github.com/zyantific/zasm). zasm also provides an idiomatic C++ wrapper around the decoder and formatter interface. ## Versions ### Scheme Versions follow the [semantic versioning scheme](https://semver.org/). All stability guarantees apply to the API only. ABI stability is provided only between patch versions. ### Branches & Tags - `master` holds the bleeding edge code of the next, unreleased Zydis version. Elevated amounts of bugs and issues must be expected, API stability is not guaranteed outside of tagged commits. - Stable and preview versions are annotated with git tags - beta and other preview versions have `-beta`, `-rc`, etc. suffixes - `maintenance/v3` points to the code of the latest release of v3 - v3 won't get any feature updates but will receive security updates until 2025 - `maintenance/v2` points to the code of the last legacy release of v2 - v2 is has reached end-of-life and won't receive any security updates ## Credits - Intel (for open-sourcing [XED](https://github.com/intelxed/xed), allowing for automatic comparison of our tables against theirs, improving both) - [LLVM](https://llvm.org) (for providing pretty solid instruction data as well) - Christian Ludloff (https://sandpile.org, insanely helpful) - [LekoArts](https://www.lekoarts.de/) (for creating the project logo) - Our [contributors on GitHub](https://github.com/zyantific/zydis/graphs/contributors) ## Troubleshooting ### `-fPIC` for shared library builds ``` /usr/bin/ld: ./libfoo.a(foo.c.o): relocation R_X86_64_PC32 against symbol `bar' can not be used when making a shared object; recompile with -fPIC ``` Under some circumstances (e.g. when building Zydis as a static library using CMake and then using Makefiles to manually link it into a shared library), CMake might fail to detect that relocation information must be emitted. This can be forced by passing `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` to the CMake invocation. ## Consulting and Business Support We offer consulting services and professional business support for Zydis. If you need a custom extension, require help in integrating Zydis into your product or simply want contractually guaranteed updates and turnaround times, we are happy to assist with that! Please contact us at business@zyantific.com. ## Donations Donations are collected and distributed using [flobernd](https://github.com/users/flobernd/sponsorship)'s account. ## License Zydis is licensed under the MIT license. --- ### Overview (`pcsx2/Docs/Documentation_README.md`) # Documentation Artifacts - Source Directory: `/pcsx2/pcsx2/Docs` - Release Directory: `/pcsx2/bin/Docs` Docs should be written in the source directory first in an easily editable format. Currently, Markdown is the preferred format due to its simple markup and easy portability. GitHub's built-in preview functions are a huge benefit as well. Visual Studio Code is a cross platform text editor/development platform that can handle Markdown syntax, plus extensions are available to enable in-editor previewing and PDF generation. However, this is not a requirement since other editors will support Markdown, and worst case GitHub supports editing Markdown files in-browser. ## How to Generate ### Setup To generate the documentation artifacts into the release directory, you will require the following: - `pandoc` - Converts from Markdown to PDF - `miktex` or something similar that provides `pdflatex` - this is what generates the PDF file #### Linux / MacOS Consult pandoc's official documentation - https://pandoc.org/installing.html #### Windows In a PowerShell shell, run the following: ```ps1 > iwr -useb get.scoop.sh | iex > scoop install pandoc latex ``` If you prefer Chocolatey or using the installer, consult pandoc's official documentation - https://pandoc.org/installing.html ### Usage Run the following, this assumes you have access to bash, either by virtue of running on linux or through something like `git-bash` on Windows. ```bash > ./gen-docs.sh ``` > You can override the default output directory like so - `OUT_DIR= ./gen-docs.sh` ### Customizing Output For generating the PDF's this popular template is used and has many features that could be useful https://github.com/Wandmalfarbe/pandoc-latex-template#usage reference it's documentation to take advantage of those if desired. --- ### Overview (`pcsx2/Docs/README.md`) # PCSX2 PCSX2 is a Playstation 2 emulator for Windows, Linux and Mac. The project has been going since 2001 and still going strong, with contributions from many very clever developers over the years! PCSX2 has compatibility upwards of 95% of the Playstation 2 library being playable. ## Basic usage For information on how to set up the emulator, please see our [basic setup](https://pcsx2.net/guides/basic-setup/) guide. ## Contributing Pull requests are welcome and can be submitted at our [GitHub page](https://github.com/PCSX2/pcsx2/) Please make sure to follow our coding style guide and fill out the pull request forms with the appropriate information. ## License [GPL 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) ## Donating to the project If you wish to donate monetarily to the project you can do so via the [GitHub Sponsors](https://github.com/sponsors/PCSX2). All donations are gratefully received! ## Thanks to the following monthly donators We thank everybody for their contributions to the project, but we would like to give a special shout out to: - noigeaR - xTVaser - jrdnhnz --- ### Overview (`.github/workflows/architecture/README.md`) # CI Documentation ## Releases ```mermaid sequenceDiagram PCSX2 Repo->>Actions: PR is merged or commit is pushed to master Actions->>PCSX2 Repo: Increment latest tag and push, create a draft release Actions->>Actions: Kicked off pipeline on the tag push, build relevant configs Actions->>PCSX2 Repo: Rename and upload artifacts to draft release, publish the release Actions->>Discord: Announce release via a WebHook PCSX2 Repo->>Web API: POST webhook to API informing it that a new release has occurred Web API->>Web API: Update cache with new release ``` --- ### Overview (`3rdparty/googletest/googlemock/README.md`) # Googletest Mocking (gMock) Framework ### Overview Google's framework for writing and using C++ mock classes. It can help you derive better designs of your system and write better tests. It is inspired by: * [jMock](http://www.jmock.org/) * [EasyMock](https://easymock.org/) * [Hamcrest](https://code.google.com/p/hamcrest/) It is designed with C++'s specifics in mind. gMock: - Provides a declarative syntax for defining mocks. - Can define partial (hybrid) mocks, which are a cross of real and mock objects. - Handles functions of arbitrary types and overloaded functions. - Comes with a rich set of matchers for validating function arguments. - Uses an intuitive syntax for controlling the behavior of a mock. - Does automatic verification of expectations (no record-and-replay needed). - Allows arbitrary (partial) ordering constraints on function calls to be expressed. - Lets a user extend it by defining new matchers and actions. - Does not use exceptions. - Is easy to learn and use. Details and examples can be found here: * [gMock for Dummies](https://google.github.io/googletest/gmock_for_dummies.html) * [Legacy gMock FAQ](https://google.github.io/googletest/gmock_faq.html) * [gMock Cookbook](https://google.github.io/googletest/gmock_cook_book.html) * [gMock Cheat Sheet](https://google.github.io/googletest/gmock_cheat_sheet.html) GoogleMock is a part of [GoogleTest C++ testing framework](https://github.com/google/googletest/) and a subject to the same requirements. --- ### Overview (`3rdparty/googletest/googletest/README.md`) ### Generic Build Instructions #### Setup To build GoogleTest and your tests that use it, you need to tell your build system where to find its headers and source files. The exact way to do it depends on which build system you use, and is usually straightforward. ### Build with CMake GoogleTest comes with a CMake build script ([CMakeLists.txt](https://github.com/google/googletest/blob/main/CMakeLists.txt)) that can be used on a wide range of platforms ("C" stands for cross-platform.). If you don't have CMake installed already, you can download it for free from . CMake works by generating native makefiles or build projects that can be used in the compiler environment of your choice. You can either build GoogleTest as a standalone project or it can be incorporated into an existing CMake build for another project. #### Standalone CMake Project When building GoogleTest as a standalone project, the typical workflow starts with ``` git clone https://github.com/google/googletest.git -b v1.18.0 cd googletest # Main directory of the cloned repository. mkdir build # Create a directory to hold the build output. cd build cmake .. # Generate native build scripts for GoogleTest. ``` The above command also includes GoogleMock by default. And so, if you want to build only GoogleTest, you should replace the last command with ``` cmake .. -DBUILD_GMOCK=OFF ``` If you are on a \*nix system, you should now see a Makefile in the current directory. Just type `make` to build GoogleTest. And then you can simply install GoogleTest if you are a system administrator. ``` make sudo make install # Install in /usr/local/ by default ``` If you use Windows and have Visual Studio installed, a `gtest.sln` file and several `.vcproj` files will be created. You can then build them using Visual Studio. On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated. #### Incorporating Into An Existing CMake Project If you want to use GoogleTest in a project which already uses CMake, the easiest way is to get installed libraries and headers. * Import GoogleTest by using `find_package` (or `pkg_check_modules`). For example, if `find_package(GTest CONFIG REQUIRED)` succeeds, you can use the libraries as `GTest::gtest`, `GTest::gmock`. And a more robust and flexible approach is to build GoogleTest as part of that project directly. This is done by making the GoogleTest source code available to the main build and adding it using CMake's `add_subdirectory()` command. This has the significant advantage that the same compiler and linker settings are used between GoogleTest and the rest of your project, so issues associated with using incompatible libraries (eg debug/release), etc. are avoided. This is particularly useful on Windows. Making GoogleTest's source code available to the main build can be done a few different ways: * Download the GoogleTest source code manually and place it at a known location. This is the least flexible approach and can make it more difficult to use with continuous integration systems, etc. * Embed the GoogleTest source code as a direct copy in the main project's source tree. This is often the simplest approach, but is also the hardest to keep up to date. Some organizations may not permit this method. * Add GoogleTest as a git submodule or equivalent. This may not always be possible or appropriate. Git submodules, for example, have their own set of advantages and drawbacks. * Use CMake to download GoogleTest as part of the build's configure step. This approach doesn't have the limitations of the other methods. The last of the above methods is implemented with a small piece of CMake code that downloads and pulls the GoogleTest code into the main build. Just add to your `CMakeLists.txt`: ```cmake include(FetchContent) FetchContent_Declare( googletest # Specify the commit you depend on and update it regularly. URL https://github.com/google/googletest/archive/5376968f6948923e2411081fd9372e71a59d8e77.zip ) # For Windows: Prevent overriding the parent project's compiler/linker settings set(gtest_force_shared_crt ON CACHE BOOL "" FORCE) FetchContent_MakeAvailable(googletest) # Now simply link against gtest or gtest_main as needed. Eg add_executable(example example.cpp) target_link_libraries(example gtest_main) add_test(NAME example_test COMMAND example) ``` Note that this approach requires CMake 3.14 or later due to its use of the `FetchContent_MakeAvailable()` command. ##### Visual Studio Dynamic vs Static Runtimes By default, new Visual Studio projects link the C runtimes dynamically but GoogleTest links them statically. This will generate an error that looks something like the following: gtest.lib(gtest-all.obj) : error LNK2038: mismatch detected for 'RuntimeLibrary': value 'MTd_StaticDebug' doesn't match value 'MDd_DynamicDebug' in main.obj GoogleTest already has a CMake option for this: `gtest_force_shared_crt` Enabling this option will make gtest link the runtimes dynamically too, and match the project in which it is included. #### C++ Standard Version An environment that supports C++17 is required in order to successfully build GoogleTest. One way to ensure this is to specify the standard in the top-level project, for example by using the `set(CMAKE_CXX_STANDARD 17)` command along with `set(CMAKE_CXX_STANDARD_REQUIRED ON)`. If this is not feasible, for example in a C project using GoogleTest for validation, then it can be specified by adding it to the options for cmake via the`-DCMAKE_CXX_FLAGS` option. ### Tweaking GoogleTest GoogleTest can be used in diverse environments. The default configuration may not work (or may not work well) out of the box in some environments. However, you can easily tweak GoogleTest by defining control macros on the compiler command line. Generally, these macros are named like `GTEST_XYZ` and you define them to either 1 or 0 to enable or disable a certain feature. We list the most frequently used macros below. For a complete list, see file [include/gtest/internal/gtest-port.h](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-port.h). ### Multi-threaded Tests GoogleTest is thread-safe where the pthread library is available. After `#include `, you can check the `GTEST_IS_THREADSAFE` macro to see whether this is the case (yes if the macro is `#defined` to 1, no if it's undefined.). If GoogleTest doesn't correctly detect whether pthread is available in your environment, you can force it with ``` -DGTEST_HAS_PTHREAD=1 ``` or ``` -DGTEST_HAS_PTHREAD=0 ``` When GoogleTest uses pthread, you may need to add flags to your compiler and/or linker to select the pthread library, or you'll get link errors. If you use the CMake script, this is taken care of for you. If you use your own build script, you'll need to read your compiler and linker's manual to figure out what flags to add. ### As a Shared Library (DLL) GoogleTest is compact, so most users can build and link it as a static library for the simplicity. You can choose to use GoogleTest as a shared library (known as a DLL on Windows) if you prefer. To compile *gtest* as a shared library, add ``` -DGTEST_CREATE_SHARED_LIBRARY=1 ``` to the compiler flags. You'll also need to tell the linker to produce a shared library instead - consult your linker's manual for how to do it. To compile your *tests* that use the gtest shared library, add ``` -DGTEST_LINKED_AS_SHARED_LIBRARY=1 ``` to the compiler flags. Note: while the above steps aren't technically necessary today when using some compilers (e.g. GCC), they may become necessary in the future, if we decide to improve the speed of loading the library (see for details). Therefore you are recommended to always add the above flags when using GoogleTest as a shared library. Otherwise a future release of GoogleTest may break your build script. ### Avoiding Macro Name Clashes In C++, macros don't obey namespaces. Therefore two libraries that both define a macro of the same name will clash if you `#include` both definitions. In case a GoogleTest macro clashes with another library, you can force GoogleTest to rename its macro to avoid the conflict. Specifically, if both GoogleTest and some other code define macro FOO, you can add ``` -DGTEST_DONT_DEFINE_FOO=1 ``` to the compiler flags to tell GoogleTest to change the macro's name from `FOO` to `GTEST_FOO`. Currently `FOO` can be `ASSERT_EQ`, `ASSERT_FALSE`, `ASSERT_GE`, `ASSERT_GT`, `ASSERT_LE`, `ASSERT_LT`, `ASSERT_NE`, `ASSERT_TRUE`, `EXPECT_FALSE`, `EXPECT_TRUE`, `FAIL`, `SUCCEED`, `TEST`, or `TEST_F`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll need to write ``` GTEST_TEST(SomeTest, DoesThis) { ... } ``` instead of ``` TEST(SomeTest, DoesThis) { ... } ``` in order to define a test. --- ### Overview (`3rdparty/vulkan/include/README.md`) # Vulkan Memory Allocator Easy to integrate Vulkan memory allocation library. **Documentation:** Browse online: [Vulkan Memory Allocator](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/) (generated from Doxygen-style comments in [include/vk_mem_alloc.h](include/vk_mem_alloc.h)) **License:** MIT. See [LICENSE.txt](LICENSE.txt) **Changelog:** See [CHANGELOG.md](CHANGELOG.md) **Product page:** [Vulkan Memory Allocator on GPUOpen](https://gpuopen.com/vulkan-memory-allocator/) [](http://isitmaintained.com/project/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator "Average time to resolve an issue") # Problem Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics APIs, like D3D11 or OpenGL) for several reasons: - It requires a lot of boilerplate code, just like everything else in Vulkan, because it is a low-level and high-performance API. - There is additional level of indirection: `VkDeviceMemory` is allocated separately from creating `VkBuffer`/`VkImage` and they must be bound together. - Driver must be queried for supported memory heaps and memory types. Different GPU vendors provide different types of it. - It is recommended to allocate bigger chunks of memory and assign parts of them to particular resources, as there is a limit on maximum number of memory blocks that can be allocated. # Features This library can help game developers to manage memory allocations and resource creation by offering some higher-level functions: 1. Functions that help to choose correct and optimal memory type based on intended usage of the memory. - Required or preferred traits of the memory are expressed using higher-level description comparing to Vulkan flags. 2. Functions that allocate memory blocks, reserve and return parts of them (`VkDeviceMemory` + offset + size) to the user. - Library keeps track of allocated memory blocks, used and unused ranges inside them, finds best matching unused ranges for new allocations, respects all the rules of alignment and buffer/image granularity. 3. Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call. Additional features: - Well-documented - description of all functions and structures provided, along with chapters that contain general description and example code. - Thread-safety: Library is designed to be used in multithreaded code. Access to a single device memory block referred by different buffers and textures (binding, mapping) is synchronized internally. Memory mapping is reference-counted. - Configuration: Fill optional members of `VmaAllocatorCreateInfo` structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters. - Customization and integration with custom engines: Predefine appropriate macros to provide your own implementation of all external facilities used by the library like assert, mutex, atomic. - Support for memory mapping, reference-counted internally. Support for persistently mapped memory: Just allocate with appropriate flag and access the pointer to already mapped memory. - Support for non-coherent memory. Functions that flush/invalidate memory. `nonCoherentAtomSize` is respected automatically. - Support for resource aliasing (overlap). - Support for sparse binding and sparse residency: Convenience functions that allocate or free multiple memory pages at once. - Custom memory pools: Create a pool with desired parameters (e.g. fixed or limited maximum size) and allocate memory out of it. - Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion. - Support for Vulkan 1.0...1.4. - Support for extensions (and equivalent functionality included in new core Vulkan versions): - VK_KHR_dedicated_allocation: Just enable it and it will be used automatically by the library. - VK_KHR_bind_memory2. - VK_KHR_maintenance4. - VK_KHR_maintenance5, including `VkBufferUsageFlags2CreateInfoKHR`. - VK_EXT_memory_budget: Used internally if available to query for current usage and budget. If not available, it falls back to an estimation based on memory heap sizes. - VK_KHR_buffer_device_address: Flag `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR` is automatically added to memory allocations where needed. - VK_EXT_memory_priority: Set `priority` of allocations or custom pools and it will be set automatically using this extension. - VK_AMD_device_coherent_memory. - VK_KHR_external_memory_win32. - Defragmentation of GPU and CPU memory: Let the library move data around to free some memory blocks and make your allocations better compacted. - Statistics: Obtain brief or detailed statistics about the amount of memory used, unused, number of allocated blocks, number of allocations etc. - globally, per memory heap, and per memory type. - Debug annotations: Associate custom `void* pUserData` and debug `char* pName` with each allocation. - JSON dump: Obtain a string in JSON format with detailed map of internal state, including list of allocations, their string names, and gaps between them. - Convert this JSON dump into a picture to visualize your memory. See [tools/GpuMemDumpVis](tools/GpuMemDumpVis/README.md). - Debugging incorrect memory usage: Enable initialization of all allocated memory with a bit pattern to detect usage of uninitialized or freed memory. Enable validation of a magic number after every allocation to detect out-of-bounds memory corruption. - Support for interoperability with OpenGL, Direct3D, and other graphics APIs through external memory export. - Virtual allocator: Interface for using core allocation algorithm to allocate any custom data, e.g. pieces of one large buffer. # Prerequisites - Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan. Some features of C++14 used. STL containers, RTTI, or C++ exceptions are not used. - Public interface in C, in same convention as Vulkan API. Implementation in C++. - Error handling implemented by returning `VkResult` error codes - same way as in Vulkan. - Interface documented using Doxygen-style comments. - Platform-independent, but developed and tested on Windows using Visual Studio. Continuous integration setup for Windows and Linux. Used also on Android, MacOS, and other platforms. # Example Basic usage of this library is very simple. Advanced features are optional. After you created global `VmaAllocator` object, a complete code needed to create a buffer may look like this: ```cpp VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO }; bufferInfo.size = 65536; bufferInfo.usage = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT; VmaAllocationCreateInfo allocInfo = {}; allocInfo.usage = VMA_MEMORY_USAGE_AUTO; VkBuffer buffer; VmaAllocation allocation; vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr); ``` With this one function call: 1. `VkBuffer` is created. 2. `VkDeviceMemory` block is allocated if needed. 3. An unused region of the memory block is bound to this buffer. `VmaAllocation` is an object that represents memory assigned to this buffer. It can be queried for parameters like `VkDeviceMemory` handle and offset. # How to build On Windows it is recommended to use [CMake GUI](https://cmake.org/runningcmake/). Alternatively you can generate/open a Visual Studio from the command line: ```sh # By default CMake picks the newest version of Visual Studio it can use cmake -S . -B build -D VMA_BUILD_SAMPLES=ON cmake --open build ``` On Linux: ```sh cmake -S . -B build # Since VMA has no source files, you can skip to installation immediately cmake --install build --prefix build/install ``` ## How to use After calling either `find_package` or `add_subdirectory` simply link the library. This automatically handles configuring the include directory. Example: ```cmake find_package(VulkanMemoryAllocator CONFIG REQUIRED) target_link_libraries(YourGameEngine PRIVATE GPUOpen::VulkanMemoryAllocator) ``` For more info on using CMake visit the official [CMake documentation](https://cmake.org/cmake/help/latest/index.html). ## Building using vcpkg You can download and install VulkanMemoryAllocator using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: git clone https://github.com/Microsoft/vcpkg.git cd vcpkg ./bootstrap-vcpkg.sh ./vcpkg integrate install ./vcpkg install vulkan-memory-allocator The VulkanMemoryAllocator port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. # Binaries The release comes with precompiled binary executable for "VulkanSample" application which contains test suite. It is compiled using Visual Studio 2022, so it requires appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If the launch fails with error message telling about those files missing, please download and install [Microsoft Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads), "X64" version. # Read more See **[Documentation](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/)**. # Software using this library - **[Blender](https://www.blender.org)** - **[Qt Project](https://github.com/qt)** - **[Baldur's Gate III](https://www.mobygames.com/game/150689/baldurs-gate-iii/credits/windows/?autoplatform=true)** - **[Cyberpunk 2077](https://www.mobygames.com/game/128136/cyberpunk-2077/credits/windows/?autoplatform=true)** - **[X-Plane](https://x-plane.com/)** - **[Detroit: Become Human](https://gpuopen.com/learn/porting-detroit-3/)** - **[Vulkan Samples](https://github.com/LunarG/VulkanSamples)** - official Khronos Vulkan samples. License: Apache-style. - **[GFXReconstruct](https://github.com/LunarG/gfxreconstruct)** - a tools for the capture and replay of graphics API calls. License: MIT. - **[Anvil](https://github.com/GPUOpen-LibrariesAndSDKs/Anvil)** - cross-platform framework for Vulkan. License: MIT. - **[Filament](https://github.com/google/filament)** - physically based rendering engine for Android, Windows, Linux and macOS, from Google. Apache License 2.0. - **[Atypical Games - proprietary game engine](https://developer.samsung.com/galaxy-gamedev/gamedev-blog/infinitejet.html)** - **[Flax Engine](https://flaxengine.com/)** - **[Godot Engine](https://github.com/godotengine/godot/)** - multi-platform 2D and 3D game engine. License: MIT. - **[Lightweight Java Game Library (LWJGL)](https://www.lwjgl.org/)** - includes binding of the library for Java. License: BSD. - **[LightweightVK](https://github.com/corporateshark/lightweightvk)** - lightweight C++ bindless Vulkan 1.3 wrapper. License: MIT. - **[PowerVR SDK](https://github.com/powervr-graphics/Native_SDK)** - C++ cross-platform 3D graphics SDK, from Imagination. License: MIT. - **[Skia](https://github.com/google/skia)** - complete 2D graphic library for drawing Text, Geometries, and Images, from Google. - **[The Forge](https://github.com/ConfettiFX/The-Forge)** - cross-platform rendering framework. Apache License 2.0. - **[VK9](https://github.com/disks86/VK9)** - Direct3D 9 compatibility layer using Vulkan. Zlib license. - **[vkDOOM3](https://github.com/DustinHLand/vkDOOM3)** - Vulkan port of GPL DOOM 3 BFG Edition. License: GNU GPL. - **[vkQuake2](https://github.com/kondrak/vkQuake2)** - vanilla Quake 2 with Vulkan support. License: GNU GPL. - **[Vulkan Best Practice for Mobile Developers](https://github.com/ARM-software/vulkan_best_practice_for_mobile_developers)** from ARM. License: MIT. - **[RPCS3](https://github.com/RPCS3/rpcs3)** - PlayStation 3 emulator/debugger. License: GNU GPLv2. - **[PPSSPP](https://github.com/hrydgard/ppsspp)** - Playstation Portable emulator/debugger. License: GNU GPLv2+. - **[Wicked Engine](https://github.com/turanszkij/WickedEngine)** - 3D engine with modern graphics [Many other projects on GitHub](https://github.com/search?q=AMD_VULKAN_MEMORY_ALLOCATOR_H&type=Code) and some game development studios that use Vulkan in their games. # See also - **[D3D12 Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator)** - equivalent library for Direct3D 12. License: MIT. - **[Awesome Vulkan](https://github.com/vinjn/awesome-vulkan)** - a curated list of awesome Vulkan libraries, debuggers and resources. - **[vcpkg](https://github.com/Microsoft/vcpkg)** dependency manager from Microsoft also offers a port of this library. - **[VulkanMemoryAllocator-Hpp](https://github.com/YaaZ/VulkanMemoryAllocator-Hpp)** - C++ binding for this library. License: CC0-1.0. - **[PyVMA](https://github.com/realitix/pyvma)** - Python wrapper for this library. Author: Jean-Sébastien B. (@realitix). License: Apache 2.0. - **[vk-mem](https://github.com/gwihlidal/vk-mem-rs)** - Rust binding for this library. Author: Graham Wihlidal. License: Apache 2.0 or MIT. - **[Haskell bindings](https://hackage.haskell.org/package/VulkanMemoryAllocator)**, **[github](https://github.com/expipiplus1/vulkan/tree/master/VulkanMemoryAllocator)** - Haskell bindings for this library. Author: Ellie Hermaszewska (@expipiplus1). License BSD-3-Clause. - **[vma_sample_sdl](https://github.com/rextimmy/vma_sample_sdl)** - SDL port of the sample app of this library (with the goal of running it on multiple platforms, including MacOS). Author: @rextimmy. License: MIT. - **[vulkan-malloc](https://github.com/dylanede/vulkan-malloc)** - Vulkan memory allocation library for Rust. Based on version 1 of this library. Author: Dylan Ede (@dylanede). License: MIT / Apache 2.0. --- ### Overview (`3rdparty/cpuinfo/deps/clog/README.md`) # clog: C-style (a-la printf) logging library [](https://github.com/pytorch/cpuinfo/blob/master/deps/clog/LICENSE) C-style library for logging errors, warnings, information notes, and debug information. ## Features - printf-style interface for formatting variadic parameters. - Separate functions for logging errors, warnings, information notes, and debug information. - Independent logging settings for different modules. - Logging to logcat on Android and stderr/stdout on other platforms. - Compatible with C99 and C++. - Covered with unit tests. ## Example ```c #include #ifndef MYMODULE_LOG_LEVEL #define MYMODULE_LOG_LEVEL CLOG_DEBUG #endif CLOG_DEFINE_LOG_DEBUG(mymodule_, "My Module", MYMODULE_LOG_LEVEL); CLOG_DEFINE_LOG_INFO(mymodule_, "My Module", MYMODULE_LOG_LEVEL); CLOG_DEFINE_LOG_WARNING(mymodule_, "My Module", MYMODULE_LOG_LEVEL); CLOG_DEFINE_LOG_ERROR(mymodule_, "My Module", MYMODULE_LOG_LEVEL); ... void some_function(...) { int status = ... if (status != 0) { mymodule_log_error( "something really bad happened: " "operation failed with status %d", status); } uint32_t expected_zero = ... if (expected_zero != 0) { mymodule_log_warning( "something suspicious happened (var = %"PRIu32"), " "fall back to generic implementation", expected_zero); } void* usually_non_null = ... if (usually_non_null == NULL) { mymodule_log_info( "something unusual, but common, happened: " "enabling work-around"); } float a = ... mymodule_log_debug("computed a = %.7f", a); } ``` --- ### Overview (`3rdparty/zydis/dependencies/zycore/README.md`) # Zyan Core Library for C License: MIT GitHub Actions Discord Internal library providing platform independent types, macros and a fallback for environments without LibC. ## Features - Platform independent types - Integer types (`ZyanU8`, `ZyanI32`, `ZyanUSize`, ...) - `ZyanBool` (+ `ZYAN_FALSE`, `ZYAN_TRUE`) - `ZYAN_NULL` - Macros - Compiler/Platform/Architecture detection - Asserts and static asserts - Utils (`ARRAY_LENGTH`, `FALLTHROUGH`, `UNUSED`, ...) - Common types - `ZyanBitset` - `ZyanString`/`ZyanStringView` - Container types - `ZyanVector` - `ZyanList` - LibC abstraction (WiP) ## License Zycore is licensed under the MIT license. --- ### Overview (`3rdparty/googletest/googlemock/include/gmock/internal/custom/README.md`) # Customization Points The custom directory is an injection point for custom user configurations. ## Header `gmock-port.h` The following macros can be defined: ### Flag related macros: * `GMOCK_DECLARE_bool_(name)` * `GMOCK_DECLARE_int32_(name)` * `GMOCK_DECLARE_string_(name)` * `GMOCK_DEFINE_bool_(name, default_val, doc)` * `GMOCK_DEFINE_int32_(name, default_val, doc)` * `GMOCK_DEFINE_string_(name, default_val, doc)` * `GMOCK_FLAG_GET(flag_name)` * `GMOCK_FLAG_SET(flag_name, value)` --- ### Overview (`3rdparty/googletest/googletest/include/gtest/internal/custom/README.md`) # Customization Points The custom directory is an injection point for custom user configurations. ## Header `gtest.h` ### The following macros can be defined: * `GTEST_OS_STACK_TRACE_GETTER_` - The name of an implementation of `OsStackTraceGetterInterface`. * `GTEST_CUSTOM_TEMPDIR_FUNCTION_` - An override for `testing::TempDir()`. See `testing::TempDir` for semantics and signature. ## Header `gtest-port.h` The following macros can be defined: ### Logging: * `GTEST_LOG_(severity)` * `GTEST_CHECK_(condition)` * Functions `LogToStderr()` and `FlushInfoLog()` have to be provided too. ### Threading: * `GTEST_HAS_NOTIFICATION_` - Enabled if Notification is already provided. * `GTEST_HAS_MUTEX_AND_THREAD_LOCAL_` - Enabled if `Mutex` and `ThreadLocal` are already provided. Must also provide `GTEST_DECLARE_STATIC_MUTEX_(mutex)` and `GTEST_DEFINE_STATIC_MUTEX_(mutex)` * `GTEST_EXCLUSIVE_LOCK_REQUIRED_(locks)` * `GTEST_LOCK_EXCLUDED_(locks)` ### Underlying library support features * `GTEST_HAS_CXXABI_H_` ### Exporting API symbols: * `GTEST_API_` - Specifier for exported symbols. ## Header `gtest-printers.h` * See documentation at `gtest/gtest-printers.h` for details on how to define a custom printer. --- ### Pcsx2 Docs GameIndex (`pcsx2/Docs/GameIndex.md`) # GameDB Documentation ## YAML Game Format The following is an annotated and comprehensive example of everything that can be defined for a single Game entry. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` > Note that quoting strings in YAML is optional, but certain characters are reserved like '\*' and require the string to be quoted. Be aware / use a YAML linter to avoid confusion. ## A Note on Case Sensitivity Both the serial numbers for the games, and the CRC patches are at the moment not case-sensitive and will be looked up with their lowercase representations. **However, stylistically, uppercase is preferred and may be enforced and migrated to in the future**. For example: * `SLUS-123` will be stored and looked up in the GameDB as `slus-123` * Likewise, a CRC with upper-case hex `23AF6876` will be stored and looked up as `23af6876` However, YAML is case-sensitive and will allow multiple serials that only differ on casing. To prevent mistakes, this will also throw a validation error where the first entry will be the one that wins. **Everything else can be safely assumed to be case sensitive!** ## Compatibility `compat` can be set to the following values: * `0` = Unknown Compatibility Status * `1` = Nothing * `2` = Intro * `3` = Menu * `4` = In-game * `5` = Playable * `6` = Perfect ## Rounding Modes The rounding modes are numerically based. These modes can be specified either on the **EE** (`eeRoundMode`) with(out) (`eeDivRoundMode`) or **VU** (`vuRoundMode`) or specific VUs like **VU0** (`vu0RoundMode`) or **VU1** (`vu1RoundMode`) ### Options for rounding * `0` = **Nearest** * `1` = **Negative Infinity** * `2` = **Positive Infinity** * `3` = **Chop (Zero)** * The is the common default ## Clamping Modes The clamp modes are also numerically based. * `eeClampMode` refers to the EE's FPU co-processor and COP2 * `vuClampMode` refers to the VUs in micro mode * `vu0ClampMode` refers to the VU0 in micro mode * `vu1ClampMode` refers to the VU1 in micro mode ### eeClampMode * `0` = **Disables** clamping completely * `1` = Clamp **Normally** (only clamp results) * `2` = Clamp **Extra+Preserve Sign** (clamp results as well as operands) * `3` = **Full Clamping** for FPU ### vuClampMode * `0` = **Disables** clamping completely * `1` = Clamp **Normally** (only clamp results) * `2` = Clamp **Extra** (clamp results as well as operands) * `3` = Clamp **Extra+Preserve Sign** ## GS Hardware Fixes [ ] = GameDB values { } = GUI options ( ) = Default values ### GS Hardware Mipmap Fixes * mipmap [`0` or `1`] {Off, On} Default: On (looks up GameDB) * trilinearFiltering [`0` or `1` or `2`] {None, Trilinear, Trilinear Ultra} Default: None (`0`) ### GS Hardware General Fixes * beforeDraw {`OI` with suffix } {None unless specific game GSC} Default: Automatic (No value, looks up GameDB) with valid variable name (ex. OI_BurnoutGames) * moveHandler {`MV` with suffix } {None unless specific game GSC} Default: Automatic (No value, looks up GameDB) with valid variable name (ex. MV_Ico) * afterDraw {`OO` with suffix } {None unless specific game GSC} Default: Automatic (No value, looks up GameDB) with valid variable name * conservativeFramebuffer [`0` or `1`] {Off or On} Default: On (`1`) * texturePreloading [`0` or `1` or `2`] {None, Partial or Full Hash Cache} Default: None (`0`) * deinterlace [Value between `0` to `9`] {Automatic, Off, WeaveTFF, WeaveBFF, BobTFF, BobBFF, BlendTFF, BlendBFF, AdaptiveTFF, AdaptiveBFF} Default: Automatic (No value, looks up GameDB) ### GS Hardware Renderer Fixes * accurateAlphaTest [`0` or `1`] {Off, On} Default: Off * autoFlush [`0` or `1` or `2`] {Disabled, Enabled (Sprites Only), Enabled (All Primitives)} Default: Off (`0`) * partialTargetInvalidation [`0` or `1`] {Off, On} Default: Off (`0`) * PCRTCOffsets [`0` or `1`] {Off, On} Default: Off (`0`) * PCRTCOverscan [`0` or `1`] {Off, On} Default: Off (`0`) * disableDepthSupport [`0` or `1`] {Off, On} Default: Off (`0`) * disablePartialInvalidation [`0` or `1`] {Off, On} Default: Off (`0`) * cpuFramebufferConversion [`0` or `1`] {Off, On} Default: Off (`0`) * preloadFrameData [`0` or `1`] {Off, On} Default: Off (`0`) * textureInsideRT [`0` or `1`or `2`] {Disabled, Inside Targets, Merge Targets} Default: Off (`0`) * PCRTCOverscan [`0` or `1`] {Off, On} Default: Off (`0`) * PCRTCOverscan [`0` or `1`] {Off, On} Default: Off (`0`) * cpuCLUTRender [`0` or `1` or `2`] {Disabled, Normal, Aggressive} Default: Disabled (`0`) * cpuSpriteRenderBW [Value between `0` to `10`] {Disabled, 1 (64), 2 (128), 3 (192), 4 (256), 5 (320), 6 (384), 7 (448), 8 (512), 9 (576), 10 (640)} Default: Off (`0`) * cpuSpriteRenderLevel [`0` or `1` or `2`] {Sprites only, Sprites/Triangles, Blended Sprites/Triangles} Default: Off unless cpuSpriteRenderBW has value other than Off then it is 'Sprites only' (`0`) * estimateTextureRegion [`0` or `1`] {Off, On} Default: Off (`0`) * drawBuffering [`0` or `1`] {Off, On} Default: Off (`0`) * rewriteLargeSTCoords [`0` or `1`] {Off, On} Default: Off (`0`) * targetPageRearranging [`0` or `1`] {Off, On} Default: Off (`0`) * getSkipCount {`GSC` with suffix } {None unless specific game GSC} Default: Disabled (`0`) unless valid variable name (ex. GSC_PolyphonyDigitalGames, GSC_UrbanReign, ...) * gpuPaletteConversion [`0` or `1`] {Off, On} Default: Off (`0`) * gpuTargetCLUT [`0` or `1` or `2`] {Disabled, Enabled (Exact Match), Enabled (Check Inside Target)} Default: Disabled (`0`) * minimumBlendingLevel [`0` or `1` or `2` or `3` or `4` or `5`] {Minimum, Basic, Medium, High, Full(Slow), Maximum (Very Slow)} Default: Automatic (No value, looks up GameDB) * maximumBlendingLevel [`0` or `1` or `2` or `3` or `4` or `5`] {Minimum, Basic, Medium, High, Full(Slow), Maximum (Very Slow)} Default: Automatic (No value, looks up GameDB) * recommendedBlendingLevel [`0` or `1` or `2` or `3` or `4` or `5`] {Minimum, Basic, Medium, High, Full(Slow), Maximum (Very Slow)} Default: Automatic (No value, looks up GameDB) * readTCOnClose [`0` or `1`] {Off, On} Default: Off (`0`) // Tab 3 Hardware Fixes (4th checkbox on right row 2) * limit24BitDepth [`0` or `1`or `2`] {Disabled, Prioritise Upper Bits, Prioritise Lower Bits} Default: Off (`0`) * recommendedAccurateAlphaTest [`0` or `1`] {Disabled, Advise to use AAT} Default: Off (`0`) * recommendedHWAA1 [`0` or `1`] {Disabled, Advise to use AA1} Default: Off (`0`) ### GS Hardware Upscaling Fixes * alignSprite [`0` or `1`] {Off or On} Default: Off (`0`) * mergeSprite [`0` or `1`] {Off or On} Default: Off (`0`) * forceEvenSpritePosition [`0` or `1`] {Off or On} Default: Off (`0`) * bilinearUpscale [`0` or `1` or `2`] {Automatic, Force Bilinear, Force Nearest} Default: Automatic * skipDrawStart [Value between `0` to `10000`] {0-10000} Default: Off (`0`) * skipDrawEnd [Value between `0` to `10000`] {0-10000} Default: Off (`0`) * halfPixelOffset [`0` or `1` or `2` or `3` or `4` or `5`] {Off, Normal Vertex, Special (Texture), Special (Texture Aggressive), Align to Native, Align to Native with Texture Offsets} Default: Off (`0`) * nativeScaling [`0` or `1` or `2` or `3` or `4`] {Off, Normal, Aggressive, Normal (Maintain Upscale) or Aggressive (Maintain Upscale) } Default: Normal (`0`) * nativePaletteDraw [`0` or `1`] {Off, On} Default: Off (`0`) * roundSprite [`0` or `1` or `2`] {Off, Half or Full} Default: Off (`0`) ## Game Fixes These values are case-sensitive, so take care. If you incorrectly specify a GameFix, you will get a validation error on startup. Any invalid game-fixes will be dropped from the game's list of fixes. ### Game Fixes Options * `FpuMulHack` * For Tales of Destiny: This fix addresses hanging issues. * `SoftwareRendererFMVHack` * Used for complex FMV rendering in certain games. * `SkipMPEGHack` * Prevents game hanging/freezing by skipping videos/FMVs. * `GoemonTlbHack` * Preload TLB hack to prevent TLB miss on Goemon. * `EETimingHack` * General-purpose timing hack affecting Digital Devil Saga, SSX, and others. * `InstantDMAHack` * Resolves cache emulation problems, affecting games like Fire Pro Wrestling Z. * `OPHFlagHack` * Affects games like Bleach Blade Battlers, Growlanser II and III, Wizardry. * `GIFFIFOHack` * Corrects but slows down rendering, impacting games like FIFA Street 2. * `DMABusyHack` * Affects games like Mana Khemia 1, Metal Saga, Pilot Down Behind Enemy Lines. * `VIF1StallHack` * Resolves hang issues in games like SOCOM 2 HUD and Spy Hunter. * `VIFFIFOHack` * Simulates VIF1 FIFO read ahead, affecting games like Test Drive Unlimited, Transformers. * `FullVU0SyncHack` * Enforces tight VU0 sync on every COP2 instruction. * `IbitHack` * Avoids constant recompilation in games like Scarface: The World is Yours, Crash Tag Team Racing. * `VuAddSubHack` * For Tri-Ace Games: Star Ocean 3, Radiata Stories, Valkyrie Profile 2. * `VUOverflowHack` * Checks for possible float overflows (Superman Returns). * `VUSyncHack` * Ensures synchronization between VUs and EE to fix timing issues. * `XGKickHack` * Uses accurate timing for VU XGKicks, affecting games like WRC, Erementar Gerad, Tennis Court Smash. * `BlitInternalFPSHack` * Utilizes an alternative method to calculate internal FPS to avoid false readings in some games. ## SpeedHacks These values are in a key-value format, where the value is assumed to be an integer. ### Options for SpeedHacks * `mvuFlag` * Accepted Values - `0` / `1` * Katamari Damacy has a peculiar speed bug when this speed hack is enabled (and it is by default) * `mtvu` * Accepted Values - `0` / `1` * T-bit games dislike MTVU, and some games are incompatible with MTVU. * `instantVU1` * Accepted Values - `0` / `1` * Games such as PaRappa the Rapper 2 need VU1 to sync, so you can force sync with this parameter. * `eeCycleRate` * Accepted Values - `-3` / `3` ## Memory Card Filter Override By default, the FolderMemoryCard filters save games based on the game's serial, which means that only saves whose folder names contain the game's serial are loaded. This works fine for the vast majority of games, but fails in some cases, which this override is for. ** 'Examples include multi-disc games, where later games often reuse the serial of the previous disc(s) - and games that allow transfer of savedata between different games, such as importing data from a prequel. This can unlock certain content ranging from cosmetic features (gear/ visual costume) to mechanics (early unlock of weapons). These are not needed with file memcards as they don't hide the serials or outside date from the game itself nor its save memcard. ** > Values should be specified as a list of strings, example shown above. ## Patches The patch that corresponds to the running game's CRC will take precedence over the `default`. Multiple patches using the same CRC cannot be defined and this will throw a validation error. > CRCs are case-insensitive, however uppercase is preferred stylistically! Patches should be defined as multi-line string blocks, where each line would correspond with a line in a conventional `*.pnach` file For more information on how to write a patch, see the following [forum post](https://forums.pcsx2.net/Thread-How-PNACH-files-work-2-0) ## Editor Tooling We provide a [JSON Schema](https://json-schema.org/) for the GameDB's format. You can use this to validate the file, and assist in writing it properly. ### VSCode Integration If you use VSCode and you want it to properly lint the GameIndex.yaml file you should: 1. Download the YAML extension - 2. Add the following to your settings: ```json "yaml.schemas": { "https://raw.githubusercontent.com/PCSX2/pcsx2/master/pcsx2/Docs/gamedb-schema.json": "**/GameIndex.yaml", }, ``` --- ### Pcsx2 Docs GPL (`pcsx2/Docs/GPL.txt`) GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU General Public License is a free, copyleft license for software and other kinds of works. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: Copyright (C) This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see . The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read . --- ### Pcsx2 Docs License (`pcsx2/Docs/License.txt`) This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . --- ### Pcsx2 Docs PCSX2 FAQ (`pcsx2/Docs/PCSX2_FAQ.md`) # PCSX2 - Frequently Asked Questions ## About the PCSX2 Project ### Question 1: What is the purpose of the PCSX2 project? PCSX2 intends to emulate the PlayStation 2 console, allowing PS2 games to be played on a computer. This requires having an original PlayStation 2 console to supply a BIOS dump and the original games, either to be played directly off the disc or to be dumped and played as ISO/CSO images. ### Question 2: Is PCSX2 open-source? PCSX2 is free and open-source, licensed under the GNU General Public License v3.0+. [Source code is kept on GitHub](https://github.com/pcsx2/pcsx2). ### Question 3: How can I help the project? There are a number of ways to help the project, whether it be bug reporting, game patching, or even writing code for the emulator itself. Some examples: * Want to make changes to emulator code? [Check out the issue tracker](https://github.com/PCSX2/pcsx2/issues), or [fork the PCSX2 repository and work on your own ideas](https://github.com/PCSX2/pcsx2). * Want to patch games? [Check out the cheats and patches forum thread for inspiration](https://forums.pcsx2.net/Thread-Post-your-PCSX2-cheats-patches-here). There are other threads to find as well, [such as those dedicated to 60 FPS patches](https://forums.pcsx2.net/Thread-60-fps-codes) or [widescreen patches](https://forums.pcsx2.net/Thread-PCSX2-Widescreen-Game-Patches). * Want to report bugs you have discovered in your games? Head over to [the Bug Reporting section of the PCSX2 forums](https://forums.pcsx2.net/Forum-Bug-reporting), to [the PCSX2 Discord](https://pcsx2.net/discord), or to [the GitHub issues section](https://github.com/PCSX2/pcsx2/issues). Also check out our [Issue reporting guide](https://pcsx2.net/docs/troubleshooting/identify) for information on how to better report issues to us. * Want to update us on the compatibility of your games? [Take a look at the Public Compatibility List on the PCSX2 forums](https://forums.pcsx2.net/Forum-Public-compatibility-list) * Want to improve the PCSX2 wiki? [Here is how to contribute](https://wiki.pcsx2.net/How_to_contribute) ### Question 4: Is PCSX2 ready to run out-of-the-box? No. First, you must dump your PlayStation 2 console's BIOS using the BIOS dumper. Instructions for the BIOS dumper are [available on the PCSX2 website](https://pcsx2.net/docs/setup/bios). After dumping your PlayStation 2 console's BIOS and copying it to your computer, launch PCSX2, step through the first-time setup wizard, and then you may begin playing.
--- ## Technical Details of PCSX2 ### Question 5: What are the PC requirements to use PCSX2? #### Minimum | Operating System | CPU | GPU | RAM | | --- | --- | --- | --- | | - Windows 10 Version 1809 or newer (64-bit)
- Ubuntu 22.04/Debian or newer, Arch Linux, Fedora, or other distro (64-bit)
- macOS 11.0 (Big Sur) or newer | - SSE4.1 support
- [PassMark Single Thread Performance](https://www.cpubenchmark.net/singleThread.html) rating near or greater than 1500
- Two physical cores, with simultaneous multithreading (SMT) | - Direct3D11 (Feature Level 10.0) support
- OpenGL 3.3 support
- Vulkan 1.1 support
- [PassMark G3D Mark](https://www.videocardbenchmark.net/high_end_gpus.html) rating around 3000 (GeForce GTX 750, Radeon RX 560, Intel Arc A380)
- 2 GB Video Memory | 8 GB | *Note: Recommended Single Thread Performance is based on moderately complex games. Games that pushed the PS2 hardware to its limits will struggle on CPUs at this level. Some release titles and 2D games which underutilized the PS2 hardware may run on CPUs rated as low as 1200. A quick reference for CPU **intensive games**: [Wiki](https://wiki.pcsx2.net/Category:CPU_intensive_games), [Forum](https://forums.pcsx2.net/Thread-LIST-The-Most-CPU-Intensive-Games) and CPU **light** games: [Forum](https://forums.pcsx2.net/Thread-LIST-Games-that-don-t-need-a-strong-CPU-to-emulate)* #### Recommended | Operating System | CPU | GPU | RAM | | --- | --- | --- | --- | | - Windows 10 Version 22H2 (64-bit) or newer
- Ubuntu 24.04/Debian or newer, Arch Linux, Fedora, or other distro (64-bit)
- macOS 11.0 (Big Sur) or newer | - AVX2 support
- [PassMark Single Thread Performance](https://www.cpubenchmark.net/singleThread.html) rating near or greater than 2000
- Four or more physical cores, with or without simultaneous multithreading (SMT) | - Direct3D12 support
- OpenGL 4.6 support
- Vulkan 1.3 support
- Metal Support (macOS only)
- [PassMark G3D Mark](https://www.videocardbenchmark.net/high_end_gpus.html) rating around 6000 (GeForce GTX 1650, Radeon RX 570)
- 4 GB Video Memory | 16 GB | *Note: Recommended GPU is based on 3x Internal, ~1080p resolution requirements. Higher resolutions will require stronger cards; 6x Internal, ~4K resolution will require a [PassMark G3D Mark](https://www.videocardbenchmark.net/high_end_gpus.html) rating around 12000 (GeForce GTX 1070 Ti). Just like CPU requirements, this is also highly game dependent. A quick reference for GPU **intensive games**: [Wiki](https://wiki.pcsx2.net/Category:GPU_intensive_games)* #### Heavy | Operating System | CPU | GPU | RAM | | --- | --- | --- | --- | | - Windows 10 Version 22H2 (64-bit) or newer
- Ubuntu 24.04/Debian or newer, Arch Linux, Fedora, or other distro (64-bit)
- macOS 11.0 (Big Sur) or newer | - AVX2 support
- [PassMark Single Thread Performance](https://www.cpubenchmark.net/singleThread.html) rating near or greater than 2600
- Six or more physical cores with simultaneous multithreading (SMT) | - Direct3D12 support
- OpenGL 4.6 support
- Vulkan 1.3 support
- Metal support (macOS only)
- [PassMark G3D Mark](https://www.videocardbenchmark.net/high_end_gpus.html) rating around 6000 (GeForce RTX 3050, Radeon RX 5600XT)
- 4 GB Video Memory | 16 GB | ### Question 6: How many CPU cores can PCSX2 use? By default, PCSX2 uses two cores for emulation. Enabling the MTVU speedhack allows the PS2's VU1 coprocessor to run on a third core, which is safe for most games and is generally enabled by default if possible on your CPU. Software rendering can be set to use as many or as few rendering threads as desired. We recommend using no more than 8, or the number of cores (or SMT threads) that your CPU has, whichever is the lower number.
### Question 7: Why is my CPU not using 100% of its power? The CPU load as reported in software such as Windows' Task Manager is usually a *summation* of CPU usage, across *all* cores. Software can only use the resources of the individual CPU cores it is actually running on, and cannot "borrow" CPU time from other cores. ### Question 8: Will multi-GPU (Nvidia SLI or AMD CrossFire) help with performance? No. PCSX2 does not use or require multi-GPU. ### Question 9: How do I check if a game is playable? The PCSX2 website has a [compatibility list](https://pcsx2.net/compat/) with every game that has been tested. ### Question 10: Do PS1 (PSX) games work on PCSX2? #### If you want to enjoy your PS1 games without issues: No, they will not work without issues. Please use a proper PS1 emulator, such as DuckStation or Mednafen. #### If you are a tinkerer and like to break things: PS1 games may work on PCSX2, but compatibility is very limited. Specific settings are often required to get a game to boot, and there are other universal problems including missing/pitch-shifted audio and severe FMV corruption. A [forum thread for PS1 compatibility](https://forums.pcsx2.net/Thread-PSX-Mode-Unofficial-Compatibility-List) is tracking some fixes and compatibility reports. *While we encourage discussion about PS1 games and improving compatibility, bug reports are NOT being accepted for PS1 games. Any reports for PS1 games will be closed immediately as invalid.* ### Question 11: Why does my game not work like it did in an earlier PCSX2 version? Any change to the emulator may fix one game, but cause problems for another. If the issue is severe and not fixable with different settings, you can always revert back to the last known PCSX2 version to work, and report the build number that broke the game. [Development builds](https://pcsx2.net/downloads/) are very helpful for finding the exact change that caused a regression. ### Question 12: Why is PCSX2 slow? The PlayStation 2 is a complex console, and this substantially raises the PC requirements to emulate it at full speed accurately. [This forum thread](https://forums.pcsx2.net/Thread-Why-is-PCSX2-slow) helps explain some of the technical reasons behind it, and our current guidelines for PC requirements are listed above. ### Question 13: Where do I get a PS2 BIOS? You have to dump the BIOS files from your PlayStation 2 console. There is a BIOS dumper tool [available on the PCSX2 website](https://pcsx2.net/docs/setup/bios) to do this. If you need a guide, check the bottom of this FAQ for links to BIOS guides.
### Question 14: Where do I get PS2 games? You can use games from your personal collection of discs, purchase them from local stores that resell old games, or look online at sites like eBay or Amazon. ### Question 15: Can I use PS2 discs directly with PCSX2? Yes. However, some games have speed problems, because unlike the PS2 which would constantly keep the disc spinning, PCSX2 will not do the same to your PC's disc drive. It is recommended to instead dump your games to ISO images. You can find a guide for this [on the PCSX2 website](https://pcsx2.net/docs/setup/dumping). ### Question 16: How do I play a game? If you are using an ISO image: 1) Click System > Start File. 2) Locate and click on the ISO image. If you wish to have your ISO image(s) populate in the game list: 1) Click Settings > Game List. 2) Add the directory where you keep your games if not added already. 3) It is recommended but not required that you scan this directory recursively. If you are using a disc: 1) Click System > Start Disc. ### Question 17: What is Fast Boot? Fast Boot, enabled by default, will directly mount and launch the game without first launching the PS2 BIOS. You may disable this in Settings > BIOS > Fast Boot if you wish to see the BIOS startup animation or if Fast Boot is causing an issue. ### Question 18: How do I build the PCSX2 source code? See the [build guide](https://pcsx2.net/docs/advanced/building). ### Question 19: When will the next version be released? It will be released when it is ready. Please don't waste your time and ours asking when.
--- ## PCSX2 Configuration ### Question 20: How do I configure PCSX2? Refer to the Configuration_Guide.pdf (located in the same folder as this FAQ) for an initial setup guide and resolutions or workarounds to some common known issues. ### Question 21: Will framelimiter options increase my FPS? The framelimiter has a few options that allow you to alter the pacing of your games. This will directly affect the game's speed itself, NOT your framerate, and can be useful for speeding through sections of games, or slowing down for precision. * Turbo (Tab): Bumps the framelimiter to 200%, allowing a game to run up to 2x faster than normal. * Slowmo (Shift + Tab): Drops the framelimiter to 50%, restricting a game to 0.5x its normal speed. * Framelimiter Disabled (F4): Completely disables the framelimiter. The game will run as fast as your PC can push it. ### Question 22: What is the normal speed for a PlayStation 2 game? * NTSC games will play at 59.94 FPS * PAL games will play at 50 FPS * Keep in mind that there is a difference between the internal framerate (iFPS) and what PCSX2 shows as virtual framerate (vFPS). These framerates are what the PlayStation 2 console would push to a real TV through its video cable. A game itself, typically, internally generates only half of those frames, and repeats frames to fill the gaps. This is why a "full speed" game may not "feel like 60 FPS". The console's "speed" (meaning AI, sound, physics, *everything*) is tied to the playback framerate, which is what PCSX2 reports as its "FPS". ### Question 23: What are Gamefixes? Gamefixes are specialized fixes built into PCSX2 for specific games. Gamefixes mostly fix core emulation problems that would crash or soft lock a game, rather than graphical or performance issues. By default, these are automatically enabled, meaning any games that need gamefixes will have them automatically applied, regardless of what gamefix settings you have enabled. Most games will not need gamefixes, however if your game is having issues, you can try manually enabling them in Settings > Game Properties > Game Fixes. Gamefixes are not FPS boosters; more often than not, they will degrade performance slightly.
### Question 24: What are all these EE/IOP and VU options? The PS2 EE, IOP and VU processors are substantially different from a PC CPU and require different rounding and clamping modes to do math accurately. Most games work fine on the default options, but some games might need a different setting. You can check the [PCSX2 Wiki](https://wiki.pcsx2.net/Category:Games) to see if your game needs an alternate setting, or check the [PCSX2 Forums](https://forums.pcsx2.net/) to see if anyone else has posted about it there. ### Question 25: What are PCSX2 plugins? Older versions of PCSX2 used a plugin framework for various sections of the emulator. A plugin is a small, incomplete piece of software that, when plugged in to another piece of software, provides some sort of additional function. PCSX2 used to use plugins for: * Video (GSdx) * Sound (SPU2-X) * Controls (LilyPad for Windows, OnePad for Linux) * CDVDGigzherz (CDVD) * Dev9Gigaherz (DEV9) * USB (No plugin included) In newer versions, these have been merged into the main emulator, and there is no longer a way to load external plugins. ### Question 26: Why is my sound garbled up? Your device may simply be too slow to play the game. If you have changed settings, attempt to revert them to the default, as these are usually the fastest. ### Question 27: Is my controller supported? For Windows users, PCSX2 will ship with XInput bindings already created. This will automatically work with an Xbox One controller or any other XInput controller. Bindings can easily be made for DirectInput and XInput controllers, such as Xbox 360 controllers. PS3, PS4, or Switch Pro controllers should be set up using third party compatibility software, such as Steam's Big Picture mode. For Linux and macOS users, PCSX2 will automatically detect and bind controls to any recognizable controller via SDL.
--- ## Useful Links ### BIOS Dumping Guides * [pgert's guide to BIOS and memory card tools](https://forums.pcsx2.net/Thread-An-orientation-through-some-of-the-PCSX2-BIOS-memcard-tools-Windows?pid=183709#pid183709) * [One of the original BIOS dumping guides, originally from ngemu](https://forums.pcsx2.net/Thread-Guide-to-Dumping-Your-PS2-Bios-over-LAN) ### Memory Card and Save File Guides * [pgert's guide to BIOS and memory card tools](https://forums.pcsx2.net/Thread-An-orientation-through-some-of-the-PCSX2-BIOS-memcard-tools-Windows?pid=183709#pid183709) * [An older guide on merging GameFAQs saves into PCSX2 memory cards](https://forums.pcsx2.net/Thread-How-to-use-the-myMC-tool-to-import-export-saves-from-PCSX2). Note, while the concepts in this guide are accurate, the MyMC software is old, and probably will not run on your PC without some tinkering. * [MyMC+, a newer replacement for the original MyMC referenced in the above guide](https://github.com/thestr4ng3r/mymcplus), ### PCSX2 Cheats and Patches (PNACH) * [The currently accepted master-guide to cheats and patches](https://forums.pcsx2.net/Thread-How-PNACH-files-work-2-0). * [The original guide, outdated](https://forums.pcsx2.net/Thread-How-pnach-files-work). ### PCSX2 with Netplay Support * [The latest Netplay fork of PCSX2](https://forums.pcsx2.net/Thread-PCSX2-Online-Plus). --- ### Pcsx2 Docs Gamedb Schema.Json (`pcsx2/Docs/gamedb-schema.json`) { "$id": "PCSX2 GameDB", "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "PCSX2 GameDB", "description": "JSON Schema for PCSX2's GameDB", "type": "object", "patternProperties": { "^[A-Z\\d]+-[A-Z\\d]+$": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the game, an arbitrary string" }, "name-sort": { "type": "string", "description": "The name of the game for use in sorting, an arbitrary string" }, "name-en": { "type": "string", "description": "The name of the game in ASCII, an arbitrary string" }, "region": { "type": "string", "description": "The region code for the game, for example NTSC-U", "pattern": "^(?:NTSC-(?:B|C|E|HK|J|K|M|T|U).*|PAL-?(?:A|B|E|F|G|I|M|N|P|R|S|U)?.*|Other)$" }, "compat": { "type": "integer", "description": "A number indicating the compatibility of the game. 0 (Nothing) to 6 (Perfect)", "minimum": 0, "maximum": 6 }, "roundModes": { "type": "object", "description": "Specify the rounding modes for the EE or VU. 0 (Nearest), 1 (Negative Infinity), 2 (Positive Infinity), 3 (Chop (Zero))", "properties": { "eeRoundMode": { "type": "integer", "minimum": 0, "maximum": 3 }, "eeDivRoundMode": { "type": "integer", "minimum": 0, "maximum": 3 }, "vuRoundMode": { "type": "integer", "minimum": 0, "maximum": 3 }, "vu0RoundMode": { "type": "integer", "minimum": 0, "maximum": 3 }, "vu1RoundMode": { "type": "integer", "minimum": 0, "maximum": 3 } }, "additionalProperties": false }, "clampModes": { "type": "object", "description": "Specify the clamp modes for the EE or VU.", "properties": { "eeClampMode": { "type": "integer", "description": "0 (Disables), 1 (Normally), 2 (Extra+Preserve Sign), 3 (Full Clamping)", "minimum": 0, "maximum": 3 }, "vuClampMode": { "type": "integer", "description": "0 (Disables), 1 (Normally), 2 (Extra), 3 (Extra+Preserve Sign)", "minimum": 0, "maximum": 3 }, "vu0ClampMode": { "type": "integer", "description": "0 (Disables), 1 (Normally), 2 (Extra), 3 (Extra+Preserve Sign)", "minimum": 0, "maximum": 3 }, "vu1ClampMode": { "type": "integer", "description": "0 (Disables), 1 (Normally), 2 (Extra), 3 (Extra+Preserve Sign)", "minimum": 0, "maximum": 3 } }, "additionalProperties": false }, "gameFixes": { "type": "array", "items": { "enum": [ "BlitInternalFPSHack", "DMABusyHack", "EETimingHack", "FpuMulHack", "GIFFIFOHack", "GoemonTlbHack", "IbitHack", "InstantDMAHack", "OPHFlagHack", "SkipMPEGHack", "SoftwareRendererFMVHack", "VIF1StallHack", "VIFFIFOHack", "VuAddSubHack", "VUOverflowHack", "FullVU0SyncHack", "VUSyncHack", "XGKickHack" ] }, "minItems": 1, "uniqueItems": true }, "gsHWFixes": { "type": "object", "properties": { "autoFlush": { "type": "integer", "minimum": 0, "maximum": 2 }, "conservativeFramebuffer": { "type": "integer", "minimum": 0, "maximum": 1 }, "cpuFramebufferConversion": { "type": "integer", "minimum": 0, "maximum": 1 }, "readTCOnClose": { "type": "integer", "minimum": 0, "maximum": 1 }, "disableDepthSupport": { "type": "integer", "minimum": 0, "maximum": 1 }, "preloadFrameData": { "type": "integer", "minimum": 0, "maximum": 1 }, "disablePartialInvalidation": { "type": "integer", "minimum": 0, "maximum": 1 }, "partialTargetInvalidation": { "type": "integer", "minimum": 0, "maximum": 1 }, "textureInsideRT": { "type": "integer", "minimum": 0, "maximum": 2 }, "limit24BitDepth": { "type": "integer", "minimum": 0, "maximum": 2 }, "alignSprite": { "type": "integer", "minimum": 0, "maximum": 1 }, "mergeSprite": { "type": "integer", "minimum": 0, "maximum": 1 }, "forceEvenSpritePosition": { "type": "integer", "minimum": 0, "maximum": 1 }, "bilinearUpscale": { "type": "integer", "minimum": 0, "maximum": 2 }, "nativePaletteDraw": { "type": "integer", "minimum": 0, "maximum": 1 }, "estimateTextureRegion": { "type": "integer", "minimum": 0, "maximum": 1 }, "drawBuffering": { "type": "integer", "minimum": 0, "maximum": 1 }, "rewriteLargeSTCoords": { "type": "integer", "minimum": 0, "maximum": 1 }, "targetPageRearranging": { "type": "integer", "minimum": 0, "maximum": 1 }, "PCRTCOffsets": { "type": "integer", "minimum": 0, "maximum": 1 }, "PCRTCOverscan": { "type": "integer", "minimum": 0, "maximum": 1 }, "mipmap": { "type": "integer", "minimum": 0, "maximum": 2 }, "accurateAlphaTest": { "type": "integer", "minimum": 0, "maximum": 1 }, "recommendedAccurateAlphaTest": { "type": "integer", "minimum": 0, "maximum": 1 }, "recommendedHWAA1": { "type": "integer", "minimum": 0, "maximum": 1 }, "trilinearFiltering": { "type": "integer", "minimum": 0, "maximum": 2 }, "skipDrawStart": { "type": "integer", "minimum": 0, "maximum": 100000 }, "skipDrawEnd": { "type": "integer", "minimum": 0, "maximum": 100000 }, "halfPixelOffset": { "type": "integer", "minimum": 0, "maximum": 5 }, "nativeScaling": { "type": "integer", "minimum": 0, "maximum": 4 }, "roundSprite": { "type": "integer", "minimum": 0, "maximum": 2 }, "texturePreloading": { "type": "integer", "minimum": 0, "maximum": 1 }, "deinterlace": { "type": "integer", "minimum": 0, "maximum": 9 }, "cpuSpriteRenderBW": { "type": "integer", "minimum": 1, "maximum": 10 }, "cpuSpriteRenderLevel": { "type": "integer", "minimum": 0, "maximum": 2 }, "cpuCLUTRender": { "type": "integer", "minimum": 1, "maximum": 2 }, "gpuTargetCLUT": { "type": "integer", "minimum": 0, "maximum": 2 }, "gpuPaletteConversion": { "type": "integer", "minimum": 0, "maximum": 2 }, "minimumBlendingLevel": { "type": "integer", "minimum": 0, "maximum": 5 }, "maximumBlendingLevel": { "type": "integer", "minimum": 0, "maximum": 5 }, "recommendedBlendingLevel": { "type": "integer", "minimum": 0, "maximum": 5 }, "getSkipCount": { "type": "string" }, "beforeDraw": { "type": "string" }, "moveHandler": { "type": "string" } }, "additionalProperties": false }, "memcardFilters": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z\\d]+-?[A-Z\\d]+$" }, "minItems": 1, "uniqueItems": true }, "speedHacks": { "type": "object", "properties": { "mvuFlag": { "type": "integer", "minimum": 0, "maximum": 1 }, "instantVU1": { "type": "integer", "minimum": 0, "maximum": 1 }, "mtvu": { "type": "integer", "minimum": 0, "maximum": 1 }, "eeCycleRate": { "type": "integer", "minimum": -3, "maximum": 3 } }, "additionalProperties": false }, "patches": { "type": "object", "patternProperties": { "^default|[A-Z0-9]{8}$": { "type": "object", "properties": { "content": { "type": "string" } }, "required": ["content"], "additionalProperties": false } }, "additionalProperties": false }, "dynaPatches": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "array", "items": { "type": "object", "properties": { "offset": { "type": "integer" }, "value": { "type": "integer" } }, "required": ["offset", "value"] }, "minItems": 1 }, "replacement": { "type": "array", "items": { "type": "object", "properties": { "offset": { "type": "integer" }, "value": { "type": "integer" } }, "required": ["offset", "value"] }, "minItems": 1 } }, "required": ["pattern", "replacement"] }, "minItems": 1 } }, "required": ["name", "region"], "additionalProperties": false } }, "additionalProperties": false } --- ### Pcsx2 Docs Configuration Guide Configuration Guide (`pcsx2/Docs/Configuration_Guide/Configuration_Guide.md`) # PCSX2 First Time Setup and Configuration This guide will walk through the initial setup process of PCSX2 and the basics of configuration. *Note: While this document is using Windows screenshots, you can still follow this guide for Linux.* \pagebreak ## First Time Setup The first time you launch PCSX2, you will be prompted with a First Time Configuration wizard. ### Language Selection You may choose to change the UI language of PCSX2 here. *Note: Translations may not be accurate or actively maintained by translators. If you find translation issues and want to fix them yourself, please contribute to [PCSX2 on crowdin](https://crowdin.com/project/pcsx2-emulator).* ### BIOS Selection PCSX2 will now ask you to provide your PS2's BIOS dump. Use the "Open Bios Folder" button to open the BIOS folder, and drop your BIOS files inside. Then use the "Refresh List" button to show your BIOS in the list. Click it, then hit Finish. Advanced users may wish to use a different folder for their BIOS, you can do so by hitting Browse to select a new folder. ## Post-Setup Configuration A large number of games work out-of-the-box on default PCSX2 settings. However, a subset of games require special settings to run, and some games require special settings to be upscaled. This guide will briefly cover some frequent problems and configuration settings to address them. ### General solutions Want some general ideas to try that are not specific to a game? Here are some more commonly known issues and solutions to try. *Note: For some of these issues, multiple solutions are given one after the other. Before moving from one solution to the next, **undo the previous solution**. Stacking multiple fixes on top of each other is usually unnecessary and likely to introduce new issues.* #### Grid-like pattern on screen Usually this is due to upscaling, which can cause sprites and 2D textures to misalign. Any fixes will be found in the GSdx Advanced Settings and Hacks: `Settings > Graphics` First try the two Round Sprite modes, Half and Full. Then try Align Sprite or Merge Sprite. Then try the Half Pixel Offset modes. If all else fails, consider using the Texture Offsets. #### Ghosting and bloom misalignment Upscaling can cause some screen elements, usually but not always bloom effects, to misalign. Navigate to the Upscaling fixes: `Settings > Graphics > Rendering > Upscaling fixes ` Try the various Half Pixel Offset modes. The further down the list you go, the more aggressive the hack gets. Once you find a mode that properly fixes the ghosting/misalignment, do not push it further. Also note in some games, the further you upscale, the worse the ghosting/misalignment gets. In some of these games, Half Pixel Offset may mitigate the issue, but not be able to fully resolve it. #### Flickering or improper lightning Sometimes a game uses blending for lighting effects and needs more accuracy for blending to work correctly. Navigate to the Graphics Settings: `Settings > Graphics > Rendering` Increment Blending Accuracy until the problem goes away. Note, higher Blending Accuracy substantially increases performance requirements. #### Flickering or improperly shaped shadows This can either be a GS or VU problem so solutions will vary wildly by game. ##### VU Navigate to the VU settings: `Settings > Emulation Settings > VUs` Try different combinations of VU0/VU1 Advanced Recompiler Options. Only change one of them at a time, and keep trying all possible combinations. If none of these work, Restore Defaults and then try changing the Recompiler/Interpreter modes. Only try Interpreter as a last ditch effort. #### Spikey Polygon Syndrome (SPS) SPS is the tendency of world geometry or character models to deform into wildly incorrect shapes, usually resulting in the generation of spikes. This is almost always a VU problem. Navigate to the VU settings: `Settings > Emulation Settings > VUs` Try different combinations of VU0/VU1 Advanced Recompiler Options. Only change one of them at a time, and keep trying all possible combinations. If none of these work, Restore Defaults and then try changing the Recompiler/Interpreter modes. Only try Interpreter as a last ditch effort. #### Menu items or text overlays missing This is usually a VU issue, but can sometimes be an EE issue. Navigate to the VU settings: `Settings > Emulation Settings > VUs` Try different combinations of VU0/VU1 Advanced Recompiler Options. Only change one of them at a time, and keep trying all possible combinations. If none of these work, Restore Defaults and then try changing the Recompiler/Interpreter modes. Only try Interpreter as a last ditch effort. If the issue persists, navigate to the EE settings: `Settings > Emulation Settings > EE/IOP` Try different combinations of EE/FPU Advanced Recompiler Options. Only change one of them at a time, and keep trying all possible combinations. If none of these work, Restore Defaults and then try changing the Recompiler/Interpreter modes. Only try Interpreter or Enable EE Cache as a last ditch effort. #### AI pathfinding/vision and other behaviors, progress flags not triggering, or world objects missing This is usually an EE issue, but can sometimes be a VU issue. Navigate to the EE settings: `Settings > Emulation Settings > EE/IOP` Try different combinations of EE/FPU Advanced Recompiler Options. Only change one of them at a time, and keep trying all possible combinations. If none of these work, Restore Defaults and then try changing the Recompiler/Interpreter modes. Only try Interpreter or Enable EE Cache as a last ditch effort. If the issue persists, navigate to the VU settings: `Settings > Emulation Settings > VUs` Try different combinations of VU0/VU1 Advanced Recompiler Options. Only change one of them at a time, and keep trying all possible combinations. If none of these work, Restore Defaults and then try changing the Recompiler/Interpreter modes. Only try Interpreter as a last ditch effort. There are some known issues with specific games that are programming level issues rather than configuration level; please check the [PCSX2 Wiki](https://wiki.pcsx2.net/Main_Page) if these solutions do not help. --- --- METRICS --- - Files Extracted: 32 - Estimated Token Budget: ~59292 tokens - Canonical Reference: https://codewiki.google/github.com/PCSX2/pcsx2