pcsx2 Documentation

Technical Documentation: PCSX2/pcsx2

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

PCSX2

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 and a 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 Copy Chapter

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 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.

System Requirements Copy Chapter

PCSX2 supports Windows, Linux, and Mac platforms. Our setup documentation page 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.

Contributing / Building Copy Chapter

PCSX2 supports translation into other languages using Crowdin.

See the Contribution Guide for more info on how to contribute.

Overview (`3rdparty/ccc/README.md`) Copy Section

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

It includes additional resources that are not present in the PCSX2 repository.

Documentation Copy Chapter

DWARF (.debug) Section Copy Section

• DWARF Debugging Information Format

MIPS Debug (.mdebug) Section Copy Section

• Third Eye Software and the MIPS symbol table (Peter Rowell)
• MIPS Mdebug Debugging Information (David Anderson, 1996)
• 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 Copy Section

• MIPS EABI

STABS Copy Section

• The "stabs" representation of debugging information (Julia Menapace, Jim Kingdon, and David MacKenzie, 1992-???)
• 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`) Copy Section

CPU INFOrmation library

cpuinfo is a library to detect essential for performance optimization information about host CPU.

Features Copy Chapter

• 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 Copy Chapter

Log processor name:

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:

#if CPUINFO_ARCH_ARM || CPUINFO_ARCH_ARM64
    /* 32-bit ARM-specific code here */
#endif

Check if the host CPU supports ARM NEON

cpuinfo_initialize();
if (cpuinfo_has_arm_neon()) {
    neon_implementation(arguments);
}

Check if the host CPU supports x86 AVX

cpuinfo_initialize();
if (cpuinfo_has_x86_avx()) {
    avx_implementation(arguments);
}

Check if the thread runs on a Cortex-A53 core

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):

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)

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 Copy Chapter

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 manifest (libcpuinfo.pc). Here are several examples of how to use it:

Command Line Copy Section

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:

$ 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:

$ 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 Copy Section

To use with the GNU Autotools include the following snippet in your project's configure.ac:

# 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 Copy Section

To use with Meson you just need to add dependency('libcpuinfo') as a dependency for your executable.

project(
    'MyCpuInfoProject',
    'cpp',
    meson_version: '>=0.55.0'
)

executable(
    'MyCpuInfoExecutable',
    sources: 'main.cpp',
    dependencies: dependency('libcpuinfo')
)

Bazel Copy Section

This project can be built using Bazel.

You can also use this library as a dependency to your Bazel project. Add to your MODULE.bazel file:

# 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 = "<replace_with_commit_hash>"
    remote = "https://github.com/pytorch/cpuinfo.git",
)

And to your BUILD file:

cc_binary(
    name = "cpuinfo_test",
    srcs = [
        # ...
    ],
    deps = [
        "@cpuinfo",
    ],
)

CMake Copy Section

To use with CMake use the FindPkgConfig module. Here is an example:

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 Copy Section

To use within a vanilla makefile, you can call pkg-config directly to supply compiler and linker flags using shell substitution.

CFLAGS=-g3 -Wall -Wextra -Werror ...
LDFLAGS=-lfoo ...
...
CFLAGS+= $(pkg-config --cflags libcpuinfo)
LDFLAGS+= $(pkg-config --libs libcpuinfo)

Exposed information Copy Chapter

• Processor (SoC) name
• Microarchitecture
• Usable instruction sets
• CPU frequency
• Cache
  • Size
  • Associativity
  • Line size
  • Number of partitions
  • Flags (unified, inclusive, complex hash function)
  • Topology (logical processors that share this cache level)
• TLB
  • Number of entries
  • Associativity
  • Covered page types (instruction, data)
  • Covered page sizes
• Topology information
  • Logical processors
  • Cores
  • Packages (sockets)

Supported environments: Copy Chapter

• Android
  • x86 ABI
  • x86_64 ABI
  • armeabi ABI
  • armeabiv7-a ABI
  • arm64-v8a ABI
  • mips ABI
  • mips64 ABI
• Linux
  • x86
  • x86-64
  • 32-bit ARM (ARMv5T and later)
  • ARM64
  • PowerPC64
• iOS
  • x86 (iPhone simulator)
  • x86-64 (iPhone simulator)
  • ARMv7
  • ARM64
• macOS
  • x86
  • x86-64
  • ARM64 (Apple silicon)
• Windows
  • x86
  • x86-64
  • arm64
• FreeBSD
  • x86-64

Methods Copy Chapter

• Processor (SoC) name detection
  • Using CPUID leaves 0x80000002–0x80000004 on x86/x86-64
  • Using /proc/cpuinfo on ARM
  • Using ro.chipname, ro.board.platform, ro.product.board, ro.mediatek.platform, ro.arch properties (Android)
  • Using kernel log (dmesg) on ARM Linux
  • Using Windows registry on ARM64 Windows
• Vendor and microarchitecture detection
  • Intel-designed x86/x86-64 cores (up to Sunny Cove, Goldmont Plus, and Knights Mill)
  • 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)
  • ARM-designed ARM cores (up to Cortex-A55, Cortex-A77, and Neoverse E1/V1/N2/V2)
  • Qualcomm-designed ARM cores (Scorpion, Krait, and Kryo)
  • Nvidia-designed ARM cores (Denver and Carmel)
  • Samsung-designed ARM cores (Exynos)
  • Intel-designed ARM cores (XScale up to 3rd-gen)
  • Apple-designed ARM cores (up to Lightning and Thunder)
  • Cavium-designed ARM cores (ThunderX)
  • AppliedMicro-designed ARM cores (X-Gene)
• Instruction set detection
  • Using CPUID (x86/x86-64)
  • Using /proc/cpuinfo on 32-bit ARM EABI (Linux)
  • Using microarchitecture heuristics on (32-bit ARM)
  • Using FPSID and WCID registers (32-bit ARM)
  • Using getauxval (Linux/ARM)
  • Using /proc/self/auxv (Android/ARM)
  • Using instruction probing on ARM (Linux)
  • Using CPUID registers on ARM64 (Linux)
  • Using IsProcessorFeaturePresent on ARM64 Windows
• Cache detection
  • Using CPUID leaf 0x00000002 (x86/x86-64)
  • Using CPUID leaf 0x00000004 (non-AMD x86/x86-64)
  • Using CPUID leaves 0x80000005-0x80000006 (AMD x86/x86-64)
  • Using CPUID leaf 0x8000001D (AMD x86/x86-64)
  • Using /proc/cpuinfo (Linux/pre-ARMv7)
  • Using microarchitecture heuristics (ARM)
  • Using chipset name (ARM)
  • Using sysctlbyname (Mach)
  • Using sysfs typology directories (ARM/Linux)
  • Using sysfs cache directories (Linux)
  • Using GetLogicalProcessorInformationEx on ARM64 Windows
• TLB detection
  • Using CPUID leaf 0x00000002 (x86/x86-64)
  • Using CPUID leaves 0x80000005-0x80000006 and 0x80000019 (AMD x86/x86-64)
  • Using microarchitecture heuristics (ARM)
• Topology detection
  • Using CPUID leaf 0x00000001 on x86/x86-64 (legacy APIC ID)
  • Using CPUID leaf 0x0000000B on x86/x86-64 (Intel APIC ID)
  • Using CPUID leaf 0x8000001E on x86/x86-64 (AMD APIC ID)
  • Using /proc/cpuinfo (Linux)
  • Using host_info (Mach)
  • Using GetLogicalProcessorInformationEx (Windows)
  • Using sysfs (Linux)
  • Using chipset name (ARM/Linux)

Overview (`3rdparty/cubeb/README.md`) Copy Section

libcubeb - Cross-platform Audio I/O Library

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 bindings. While originally written for use in the Firefox Web browser, a number of other software projects have adopted it.

Features Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

Prerequisites Copy Section

• 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 Copy Section

git clone https://github.com/mozilla/cubeb.git
cd cubeb
cmake -B build
cmake --build build

Better build with Rust backends Copy Section

git clone --recursive https://github.com/mozilla/cubeb.git
cd cubeb
cmake -B build -DBUILD_RUST_LIBS=ON
cmake --build build

Platform-Specific Notes Copy Section

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:

# 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 Copy Chapter

Run the test suite:

cd build
ctest

Use the interactive test tool:

./cubeb-test

License Copy Chapter

Licensed under an ISC-style license. See LICENSE for details.

Contributing Copy Chapter

Contributions are welcome! Please see the contribution guidelines and check the issue tracker.

Links Copy Chapter

• GitHub Repository
• API Documentation

Overview (`3rdparty/d3d12memalloc/README.md`) Copy Section

D3D12 Memory Allocator

Easy to integrate memory allocation library for Direct3D 12.

Documentation: Browse online: D3D12 Memory Allocator (generated from Doxygen-style comments in include/D3D12MemAlloc.h)

License: MIT. See LICENSE.txt

Changelog: See CHANGELOG.md

Product page: D3D12 Memory Allocator on GPUOpen

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 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.
• 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:

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, "X64" version.

Copyright notice

This software package uses third party software:

• Parts of the code of Vulkan Memory Allocator by AMD, license: MIT
• Parts of the code of DirectX-Graphics-Samples by Microsoft, license: MIT

For more information see NOTICES.txt.

See also

• Vcpkg dependency manager from Microsoft offers a port of this library that is easy to install.
• d3d12ma.c - C bindings for this library. Author: Mateusz Maciejewski (Matt Walky). License: MIT.
• TerraFX.Interop.D3D12MemoryAllocator - interop bindings for this library for C#, as used by TerraFX. License: MIT.
• Vulkan Memory Allocator - equivalent library for Vulkan. License: MIT.

Software using this library

• Qt Project
• Ghost of Tsushima: Director's Cut PC - Information avaliable in 11:38 of credits
• Godot Engine - multi-platform 2D and 3D game engine. License: MIT.
• The Forge - cross-platform rendering framework. Apache License 2.0.
• Wicked Engine - 3D engine with modern graphics

Some other projects on GitHub and some game development studios that use DX12 in their games.

Overview (`3rdparty/fast_float/README.md`) Copy Section

fast_float number parsing library: 4x faster than strtod Copy Chapter

Note: This library is for C++ users. C programmers should consider 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):

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.

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:

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:

#include "fast_float/fast_float.h"
#include <iostream>
#include <string>

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:

#include "fast_float/fast_float.h"
#include <iostream>
#include <string>

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:

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)) 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 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 Copy Chapter

You can also parse integer types using different bases (e.g., 2, 10, 16). The
following code will print the number 22250738585072012 three times:

#include "fast_float/fast_float.h"
#include <iostream>

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 Copy Chapter

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.

Hence, we have the following examples:

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

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<double>::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:

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) Copy Chapter

In C++20, you may use fast_float::from_chars to parse strings at compile-time,
as in the following example:

// 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 Copy Chapter

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:

std::float32_t result;
auto answer = fast_float::from_chars(f.data(), f.data() + f.size(), result);

Non-ASCII Inputs Copy Chapter

We also support UTF-16 and UTF-32 inputs, as well as ASCII/UTF-8, as in the
following example:

#include "fast_float/fast_float.h"
#include <iostream>

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 Copy Chapter

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.

#include "fast_float/fast_float.h"
#include <iostream>

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 Copy Section

#include "fast_float/fast_float.h"
#include <iostream>

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)) Copy Section

#include "fast_float/fast_float.h"
#include <iostream>

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:

#include "fast_float/fast_float.h"
#include <iostream>

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:

#include "fast_float/fast_float.h"
#include <iostream>

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 Copy Chapter

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.:

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<float>() specialization:

const uint64_t W = 12345678;
const int Q = 23;
const float result = fast_float::integer_times_pow10<float>(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 Copy Chapter

The fast_float library is part of:

• GCC (as of version 12): the from_chars function in GCC relies on fast_float,
• Chromium, the engine behind Google
  Chrome, Microsoft Edge, and Opera,
• Boost JSON, MySQL, etc.
• Blender
• WebKit, the engine behind Safari (Apple's
  web browser),
• DuckDB,
• Redis and Valkey,
• Apache Arrow where it multiplied
  the number parsing speed by two or three times,
• Google Jsonnet,
• ClickHouse.

The fastfloat algorithm is part of the LLVM standard
libraries.
There is a derived implementation part of
AdaCore. The SerenityOS operating
system
has a derived implementation that is inherited by the Ladybird
Browser.

The fast_float library provides a performance similar to that of the
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.

Packages Copy Chapter

References Copy Chapter

• Daniel Lemire, Number Parsing at a Gigabyte per
  Second, Software: Practice and Experience
  51 (8), 2021.
• Noble Mushtak, Daniel Lemire, Fast Number Parsing Without
  Fallback, Software: Practice and Experience
  53 (7), 2023.

Other programming languages Copy Chapter

• There is an R binding called
  rcppfastfloat.
• There is a Rust port of the fast_float
  library called
  fast-float-rust.
• There is a Java port of the fast_float
  library called
  FastDoubleParser. It used for important systems such as
  Jackson.
• There is a C# port of the fast_float
  library called csFastFloat.
• There is a plain C port of the fast_float library called ffc.h

How fast is it? Copy Chapter

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.

$ ./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 section for instructions on how to run our benchmarks.

Video Copy Chapter

Using as a CMake dependency Copy Chapter

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:

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):

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, like so:

CPMAddPackage(
  NAME fast_float
  GITHUB_REPOSITORY "fastfloat/fast_float"
  GIT_TAG v8.2.5)

Using as single header Copy Chapter

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:

https://github.com/fastfloat/fast_float/releases/download/v8.2.5/fast_float.h

Benchmarking Copy Chapter

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 Copy Chapter

• The fast_float library is part of the Conan package
  manager.
• It is part of the brew package
  manager.
• fast_float is available on xmake repository.
• Some Linux distribution like Fedora include fast_float (e.g., as
  fast_float-devel).

Credit Copy Chapter

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 Copy Chapter

License Copy Chapter

Overview (`3rdparty/fmt/README.md`) Copy Section

{fmt} is an open-source formatting library providing a fast and safe
alternative to C stdio and C++ iostreams.

Documentation

Cheat Sheets

Q&A: ask questions on StackOverflow with the tag
fmt.

Try {fmt} in Compiler Explorer.

Features

• Simple format API with positional
  arguments for localization
• Implementation of C++20
  std::format and
  C++23 std::print
• Format string syntax similar
  to Python's
  format
• Fast IEEE 754 floating-point formatter with correct rounding,
  shortness and round-trip guarantees using the
  Dragonbox algorithm
• Portable Unicode support
• Safe printf
  implementation
  including the POSIX extension for positional arguments
• Extensibility: support for user-defined
  types
• High performance: faster than common standard library
  implementations of (s)printf, iostreams, to_string and
  to_chars, see Speed tests and Converting a
  hundred million integers to strings per
  second
• 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
• Reliability: the library has an extensive set of
  tests and is
  continuously fuzzed
• 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
• 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 for more details.

Examples

Print to stdout (run)

#include <fmt/base.h>

int main() {
  fmt::print("Hello, world!\n");
}

Format a string (run)

std::string s = fmt::format("The answer is {}.", 42);
// s == "The answer is 42."

Format a string using positional arguments
(run)

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)

#include <fmt/chrono.h>

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)

#include <vector>
#include <fmt/ranges.h>

int main() {
  std::vector<int> v = {1, 2, 3};
  fmt::print("{}\n", v);
}

Output:

[1, 2, 3]

Check a format string at compile time

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

#include <fmt/os.h>

int main() {
  auto out = fmt::output_file("guide.txt");
  out.print("Don't {}", "Panic");
}

This can be up to 9 times faster than fprintf.

Print with colors and text styles

#include <fmt/color.h>

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 Copy Chapter

{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.

{fmt} is up to 20-30x faster than std::ostringstream and sprintf on
IEEE754 float and double formatting
(dtoa-benchmark) and faster
than double-conversion
and ryu:

Compile time and code bloat Copy Chapter

The script bloat-test.py from format-benchmark 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.

Optimized build (-O3)

{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

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 Copy Chapter

Please refer to Building the
library for
instructions on how to build the library and run the unit tests.

Benchmarks reside in a separate repository,
format-benchmarks, 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 v18 provides the
modernize-use-std-print
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.: a free, open-source, cross-platform
  real-time strategy game
• AMPL/MP: an open-source library for
  mathematical programming
• Apple's FoundationDB: an open-source,
  distributed, transactional key-value store
• Aseprite: animated sprite
  editor & pixel art tool
• AvioBook: a comprehensive aircraft
  operations suite
• Blizzard Battle.net: an online gaming
  platform
• Celestia: real-time 3D visualization of
  space
• Ceph: a scalable distributed storage system
• ccache: a compiler cache
• ClickHouse: an
  analytical database management system
• ContextVision: medical imaging software
• Contour: a modern
  terminal emulator
• CUAUV: Cornell University's autonomous
  underwater vehicle
• Drake: a planning, control, and analysis
  toolbox for nonlinear dynamical systems (MIT)
• Envoy: C++ L7 proxy and
  communication bus (Lyft)
• FiveM: a modification framework for GTA V
• fmtlog: a performant
  fmtlib-style logging library with latency in nanoseconds
• Folly: Facebook open-source
  library
• GemRB: a portable open-source implementation
  of Bioware's Infinity Engine
• Grand Mountain
  Adventure:
  a beautiful open-world ski & snowboarding game
• HarpyWar/pvpgn: Player vs
  Player Gaming Network with tweaks
• KBEngine: an open-source
  MMOG server engine
• Keypirinha: a semantic launcher for
  Windows
• Kodi (formerly xbmc): home theater software
• Knuth: high-performance Bitcoin full-node
• libunicode: a
  modern C++17 Unicode library
• MariaDB: relational database management
  system
• Microsoft Verona: research
  programming language for concurrent ownership
• MongoDB: distributed document database
• MongoDB Smasher: a small
  tool to generate randomized datasets
• OpenSpace: an open-source
  astrovisualization framework
• PenUltima Online (POL): an MMO server,
  compatible with most Ultima Online clients
• PyTorch: an open-source
  machine learning library
• quasardb: a distributed,
  high-performance, associative database
• Quill: asynchronous low-latency
  logging library
• QKW: generalizing aliasing to
  simplify navigation, and execute complex multi-line terminal
  command sequences
• redis-cerberus: a Redis
  cluster proxy
• redpanda: a 10x faster Kafka®
  replacement for mission-critical systems written in C++
• rpclib: a modern C++ msgpack-RPC server and
  client library
• Salesforce Analytics
  Cloud:
  business intelligence software
• Scylla: a Cassandra-compatible NoSQL
  data store that can handle 1 million transactions per second on a
  single server
• Seastar: an advanced, open-source
  C++ framework for high-performance server applications on modern
  hardware
• spdlog: super fast C++ logging
  library
• Stellar: financial platform
• Touch Surgery: surgery simulator
• TrinityCore:
  open-source MMORPG framework
• 🐙 userver framework: open-source
  asynchronous framework with a rich set of abstractions and database
  drivers
• Windows Terminal: the new
  Windows terminal

More...

If you are aware of other projects using this library, please let me
know by email or by submitting an
issue.

Maintainers

The {fmt} library is maintained by Victor Zverovich
(vitaut) with contributions from many other
people. See
Contributors and
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`) Copy Section

GoogleTest

Announcements Copy Section

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 is
now available.

The 1.18.x branch
requires at least C++17.

Continuous Integration

We use Google's internal systems for continuous integration.

Coming Soon

• We are planning to take a dependency on
  Abseil.

Welcome to **GoogleTest**, Google's C++ test framework! Copy Chapter

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 Copy Section

See the GoogleTest User's Guide for
documentation. We recommend starting with the
GoogleTest Primer.

More information about building GoogleTest can be found at
googletest/README.md.

Features Copy Chapter

• xUnit test framework:
  Googletest is based on the 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 Copy Chapter

GoogleTest follows Google's
Foundational C++ Support Policy.
See
this table
for a list of currently supported versions of compilers, platforms, and build
tools.

Who Is Using GoogleTest? Copy Chapter

In addition to many internal projects at Google, GoogleTest is also used by the
following notable projects:

• The Chromium projects (behind the Chrome
  browser and Chrome OS).
• The LLVM compiler.
• Protocol Buffers, Google's data
  interchange format.
• The OpenCV computer vision library.

Related Open Source Projects Copy Chapter

GTest Runner is a Qt5 based
automated test-runner and Graphical User Interface with powerful features for
Windows and Linux platforms.

GoogleTest UI 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 is an event
listener for GoogleTest that implements the
TAP protocol for test
result output. If your test runner understands TAP, you may find it useful.

gtest-parallel is a test runner that
runs tests from your binary in parallel to provide significant speed-up.

GoogleTest Adapter
is a VS Code extension allowing to view GoogleTest in a tree view and run/debug
your tests.

C++ TestMate is a VS
Code extension allowing to view GoogleTest in a tree view and run/debug your
tests.

Cornichon is a small Gherkin DSL parser
that generates stub code for GoogleTest.

Contributing Changes Copy Chapter

Please read
CONTRIBUTING.md
for details on how to contribute to this project.

Happy testing!

Overview (`3rdparty/libchdr/README.md`) Copy Section

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) and uses third party libraries that are each distributed under their own terms (see each library's license in deps/).

Overview (`3rdparty/rainterface/README.md`) Copy Section

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`) Copy Section

**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 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 Copy Chapter

An understanding about how achievements are developed may be useful, you can read more about it here.

Most of the exposed APIs are documented here

Return values Copy Section

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:

const char* rc_error_str(int ret);

Console identifiers Copy Section

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 Copy Chapter

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 for details on using the rc_client_t functions.

Server Communication Copy Chapter

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 page.

Functions Copy Section

Please see the wiki for details on the functions exposed for rapi.

Game Identification Copy Chapter

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.

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 Copy Section

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`) Copy Section

SoundTouch library

About Copy Chapter

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 and see the README file for more information and audio examples.

Version Copy Chapter

The latest stable release in Git is 2.4.1

See the README file for change history

Example Copy Chapter

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 for more usage examples and instructions how to build the software.

Ready SoundStretch application executables are available for download for Windows and Mac OS.

Language & Platforms Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 for details.

--

Also commercial license free of GPL limitations available upon request

Overview (`3rdparty/vixl/README.md`) Copy Section

VIXL: Arm Runtime Code Generation Library

Contents:

• Overview
• Licence
• Requirements
• Versioning
• Supported Arm Architecture Features
• Known limitations
• Bug reports
• 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.

Build status:

Licence

This software is covered by the licence described in the LICENCE
file.

Contributions, as pull requests or via other means, are accepted under the terms
of the same 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 - see VERSIONS for details.

Supported Arm Architecture Features

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 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.

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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
[email protected]. Please provide any steps required to recreate a bug, along with
build environment and host system information.

Usage

Running all Tests Copy Chapter

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 Copy Chapter

We have separate guides for introducing VIXL, depending on what architecture you
are targeting. A guide for working with AArch32 can be found
here, while the AArch64 guide is
here. Example source code is provided in the
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.

Overview (`3rdparty/vulkan/README.md`) Copy Section

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.
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.
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.

Contributing Copy Chapter

See the CONTRIBUTING.md

Building Copy Chapter

See BUILD.md

SDK Support Copy Chapter

Vulkan-Headers are shipped as part of the official Vulkan-SDK

C/C++ Package Manager Support Copy Chapter

Vulkan-Headers are also supported by both conan & vcpkg.

Version Tagging Scheme Copy Chapter

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`) Copy Section

Windows Implementation Libraries (WIL)

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
  (documentation):
  Smart pointers and auto-releasing resource wrappers to let you manage Windows
  API HANDLEs, HWNDs, and other resources and resource handles with
  RAII semantics.
• include/wil/win32_helpers.h
  (documentation): 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 (documentation): 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: (documentation) 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
  (documentation):
  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: This file contains the convenience macros
  that enable developers define and log telemetry. These macros use
  TraceLogging API
  to log data. This data can be viewed in tools such as
  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. 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 Copy Chapter

WIL is available on nuget.org under the name Microsoft.Windows.ImplementationLibrary. This package includes the header files under the include directory as well as a .targets file.

Consuming WIL via vcpkg Copy Chapter

WIL is also available using vcpkg under the name wil. Instructions for installing packages can be found in the vcpkg GitHub docs. In general, once vcpkg is set up on the system, you can run:

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 Copy Chapter

To get started contributing to WIL, first make sure that you have:

• The latest version of Visual Studio 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
  to the necessary workloads installed.
• The most recent Windows SDK
• Nuget downloaded and added to PATH - see Install NuGet client tools
• vcpkg available on your system. Follow their 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

You can install these with WinGet in a console command line:

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,
2. Have the path to the root of your vcpkg clone added to your PATH (i.e. the path to vcpkg.exe), or
3. 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 Copy Chapter

Visual Studio 2022 has fully integrated CMake support. 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 Copy Chapter

Microsoft's CMake Tools for Visual Studio Code make working
in VSCode easy.

1. Start a "Native Tools Command Prompt" (see below)
2. 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 Copy Chapter

Once everything is installed (you'll need to restart Terminal if you updated PATH and don't have this 2023 fix),
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 to configure the environment:

# 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 to pick the configuration:

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
(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 Copy Chapter

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..
Switch to VS Code's "testing" tab, and click the "Run Tests"
option.

For command-line CMake (configured with cmake --preset ...) build use, some examples:

# 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:

# 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 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 Copy Chapter

If you are at the tail end of of a change, you can execute the following to get a wide range of coverage:

C:\wil> scripts\init_all.cmd
C:\wil> scripts\build_all.cmd
C:\wil> scripts\runtests.cmd

Formatting Copy Chapter

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` Copy Section

Important! Git integration with clang-format is only available through the LLVM distribution.
You can install LLVM through their GibHub releases page, 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:

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:

C:\wil> git fetch upstream
C:\wil> git merge upstream/master
C:\wil> scripts\format-changes.cmd upstream/master

2. Formatting with `clang-format` Copy Section

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:

C:\wil> scripts\run-clang-format.cmd

Additionally, we've added a build target that will invoke this script, named format:

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.
For more information see the Code of Conduct FAQ or
contact [email protected] with any additional questions or comments.

Overview (`3rdparty/zydis/README.md`) Copy Section

Features Copy Chapter

• Supports all x86 and x86-64 (AMD64) instructions and extensions
• 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
• Trusted by many major open-source projects
  • Examples include x64dbg, Mozilla Firefox and 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

Examples Copy Chapter

Disassembler Copy Section

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:

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 Copy Section

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 Copy Section

More examples can be found in the examples directory of this repository.

Build Copy Chapter

There are many ways to make Zydis available on your system. The following sub-sections list commonly used options.

CMake Build Copy Section

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.

git clone --recursive 'https://github.com/zyantific/zydis.git'
cd zydis
cmake -B build
cmake --build build -j4

Visual Studio 2022 project Copy Section

Platforms: Windows

We manually maintain a Visual Studio 2022 project in addition to the CMake build logic.

CMake generated VS project Copy Section

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. Don't be confused by the apparent use of macOS in the video: Windows is simply running in a virtual machine.

Amalgamated distribution Copy Section

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
as zydis-amalgamated.tar.gz.

These files are generated with the amalgamate.py script.

Package managers Copy Section

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

Using Zydis in a CMake project Copy Chapter

An example on how to use Zydis in your own CMake based project can be found in this repo.

`ZydisInfo` tool Copy Chapter

The ZydisInfo command-line tool can be used to inspect essentially all information
that Zydis provides about an instruction.

Bindings Copy Chapter

Official bindings exist for a selection of languages:

• Rust
• Python 3

asmjit-style C++ front-end Copy Section

If you're looking for an asmjit-style assembler front-end for the encoder, check out zasm.
zasm also provides an idiomatic C++ wrapper around the decoder and formatter interface.

Versions Copy Chapter

Scheme Copy Section

Versions follow the semantic versioning scheme. All stability guarantees apply to the API only. ABI stability is provided only between patch versions.

Branches & Tags Copy Section

• 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 Copy Chapter

• Intel (for open-sourcing XED, allowing for automatic comparison of our tables against theirs, improving both)
• LLVM (for providing pretty solid instruction data as well)
• Christian Ludloff (https://sandpile.org, insanely helpful)
• LekoArts (for creating the project logo)
• Our contributors on GitHub

Troubleshooting Copy Chapter

`-fPIC` for shared library builds Copy Section

/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 Copy Chapter

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 [email protected].

Donations Copy Chapter

Donations are collected and distributed using flobernd's account.

License Copy Chapter

Zydis is licensed under the MIT license.

Overview (`pcsx2/Docs/Documentation_README.md`) Copy Section

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 Copy Chapter

Setup Copy Section

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:

> 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 Copy Section

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.

> ./gen-docs.sh

You can override the default output directory like so - OUT_DIR= ./gen-docs.sh

Customizing Output Copy Section

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`) Copy Section

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 Copy Chapter

For information on how to set up the emulator, please see our basic setup guide.

Contributing Copy Chapter

Pull requests are welcome and can be submitted at our GitHub page

Please make sure to follow our coding style guide and fill out the pull request forms with the appropriate information.

License Copy Chapter

GPL 3.0

Donating to the project Copy Chapter

If you wish to donate monetarily to the project you can do so via the GitHub Sponsors. All donations are gratefully received!

Thanks to the following monthly donators Copy Chapter

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`) Copy Section

CI Documentation

Releases Copy Chapter

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`) Copy Section

Googletest Mocking (gMock) Framework

Overview Copy Section

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
• EasyMock
• 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
• Legacy gMock FAQ
• gMock Cookbook
• gMock Cheat Sheet

GoogleMock is a part of
GoogleTest C++ testing framework and a
subject to the same requirements.

Overview (`3rdparty/googletest/googletest/README.md`) Copy Section

Generic Build Instructions Copy Section

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 Copy Section

GoogleTest comes with a CMake build script
(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
https://cmake.org/.

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:

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 Copy Section

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.

Multi-threaded Tests Copy Section

GoogleTest is thread-safe where the pthread library is available. After
#include <gtest/gtest.h>, 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) Copy Section

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
https://gcc.gnu.org/wiki/Visibility 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 Copy Section

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`) Copy Section

Vulkan Memory Allocator

Easy to integrate Vulkan memory allocation library.

Documentation: Browse online: Vulkan Memory Allocator (generated from Doxygen-style comments in include/vk_mem_alloc.h)

License: MIT. See LICENSE.txt

Changelog: See CHANGELOG.md

Product page: Vulkan Memory Allocator on GPUOpen

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.
• 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:

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.

Alternatively you can generate/open a Visual Studio from the command line:

# 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:

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 Copy Chapter

After calling either find_package or add_subdirectory simply link the library.
This automatically handles configuring the include directory. Example:

find_package(VulkanMemoryAllocator CONFIG REQUIRED)
target_link_libraries(YourGameEngine PRIVATE GPUOpen::VulkanMemoryAllocator)

For more info on using CMake visit the official CMake documentation.

Building using vcpkg Copy Chapter

You can download and install VulkanMemoryAllocator using the 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 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, "X64" version.

Read more

See Documentation.

Software using this library

• Blender
• Qt Project
• Baldur's Gate III
• Cyberpunk 2077
• X-Plane
• Detroit: Become Human
• Vulkan Samples - official Khronos Vulkan samples. License: Apache-style.
• GFXReconstruct - a tools for the capture and replay of graphics API calls. License: MIT.
• Anvil - cross-platform framework for Vulkan. License: MIT.
• Filament - physically based rendering engine for Android, Windows, Linux and macOS, from Google. Apache License 2.0.
• Atypical Games - proprietary game engine
• Flax Engine
• Godot Engine - multi-platform 2D and 3D game engine. License: MIT.
• Lightweight Java Game Library (LWJGL) - includes binding of the library for Java. License: BSD.
• LightweightVK - lightweight C++ bindless Vulkan 1.3 wrapper. License: MIT.
• PowerVR SDK - C++ cross-platform 3D graphics SDK, from Imagination. License: MIT.
• Skia - complete 2D graphic library for drawing Text, Geometries, and Images, from Google.
• The Forge - cross-platform rendering framework. Apache License 2.0.
• VK9 - Direct3D 9 compatibility layer using Vulkan. Zlib license.
• vkDOOM3 - Vulkan port of GPL DOOM 3 BFG Edition. License: GNU GPL.
• vkQuake2 - vanilla Quake 2 with Vulkan support. License: GNU GPL.
• Vulkan Best Practice for Mobile Developers from ARM. License: MIT.
• RPCS3 - PlayStation 3 emulator/debugger. License: GNU GPLv2.
• PPSSPP - Playstation Portable emulator/debugger. License: GNU GPLv2+.
• Wicked Engine - 3D engine with modern graphics

Many other projects on GitHub and some game development studios that use Vulkan in their games.

See also

• D3D12 Memory Allocator - equivalent library for Direct3D 12. License: MIT.
• Awesome Vulkan - a curated list of awesome Vulkan libraries, debuggers and resources.
• vcpkg dependency manager from Microsoft also offers a port of this library.
• VulkanMemoryAllocator-Hpp - C++ binding for this library. License: CC0-1.0.
• PyVMA - Python wrapper for this library. Author: Jean-Sébastien B. (@realitix). License: Apache 2.0.
• vk-mem - Rust binding for this library. Author: Graham Wihlidal. License: Apache 2.0 or MIT.
• Haskell bindings, github - Haskell bindings for this library. Author: Ellie Hermaszewska (@expipiplus1). License BSD-3-Clause.
• 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 - 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`) Copy Section

clog: C-style (a-la printf) logging library

C-style library for logging errors, warnings, information notes, and debug information.

Features Copy Chapter

• 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 Copy Chapter

#include <clog.h>

#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`) Copy Section

Zyan Core Library for C

Internal library providing platform independent types, macros and a fallback for environments without LibC.

Features Copy Chapter

• 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 Copy Chapter

Zycore is licensed under the MIT license.

Overview (`3rdparty/googletest/googlemock/include/gmock/internal/custom/README.md`) Copy Section

Customization Points

The custom directory is an injection point for custom user configurations.

Header `gmock-port.h` Copy Chapter

The following macros can be defined:

Flag related macros: Copy Section

• 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`) Copy Section

Customization Points

The custom directory is an injection point for custom user configurations.

Header `gtest.h` Copy Chapter

The following macros can be defined: Copy Section

• 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` Copy Chapter

The following macros can be defined:

Logging: Copy Section

• GTEST_LOG_(severity)
• GTEST_CHECK_(condition)
• Functions LogToStderr() and FlushInfoLog() have to be provided too.

Threading: Copy Section

• 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 Copy Section

• GTEST_HAS_CXXABI_H_

Exporting API symbols: Copy Section

• GTEST_API_ - Specifier for exported symbols.

Header `gtest-printers.h` Copy Chapter

• See documentation at gtest/gtest-printers.h for details on how to define a
  custom printer.

Pcsx2 Docs GameIndex (`pcsx2/Docs/GameIndex.md`) Copy Section

GameDB Documentation

YAML Game Format Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Section

• 0 = Nearest
• 1 = Negative Infinity
• 2 = Positive Infinity
• 3 = Chop (Zero)
• The is the common default

Clamping Modes Copy Chapter

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 Copy Section

• 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 Copy Section

• 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 Copy Chapter

[ ] = GameDB values
{ } = GUI options
( ) = Default values

GS Hardware Mipmap Fixes Copy Section

• 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 Copy Section

• 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 Copy Section

• 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 1or 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 1or 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 Copy Section

• 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 Copy Chapter

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 Copy Section

• 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 Copy Chapter

These values are in a key-value format, where the value is assumed to be an integer.

Options for SpeedHacks Copy Section

• 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 Copy Chapter

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 Copy Chapter

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

Editor Tooling Copy Chapter

We provide a JSON Schema for the GameDB's format. You can use this to validate the file, and assist in writing it properly.

VSCode Integration Copy Section

If you use VSCode and you want it to properly lint the GameIndex.yaml file you should:

1. Download the YAML extension - https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
2. Add the following to your settings:

"yaml.schemas": {
  "https://raw.githubusercontent.com/PCSX2/pcsx2/master/pcsx2/Docs/gamedb-schema.json": "**/GameIndex.yaml",
},

Pcsx2 Docs GPL (`pcsx2/Docs/GPL.txt`) Copy Section

GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc. http://fsf.org/
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.

<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

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 <http://www.gnu.org/licenses/>.

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) <year>  <name of author>
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
http://www.gnu.org/licenses/.

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
http://www.gnu.org/philosophy/why-not-lgpl.html.

Pcsx2 Docs License (`pcsx2/Docs/License.txt`) Copy Section

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 https://www.gnu.org/licenses/.

Pcsx2 Docs PCSX2 FAQ (`pcsx2/Docs/PCSX2_FAQ.md`) Copy Section

PCSX2 - Frequently Asked Questions

About the PCSX2 Project Copy Chapter

Question 1: What is the purpose of the PCSX2 project? Copy Section

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? Copy Section

PCSX2 is free and open-source, licensed under the GNU General Public License v3.0+. Source code is kept on GitHub.

Question 3: How can I help the project? Copy Section

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, or fork the PCSX2 repository and work on your own ideas.
• Want to patch games? Check out the cheats and patches forum thread for inspiration. There are other threads to find as well, such as those dedicated to 60 FPS patches or widescreen patches.
• Want to report bugs you have discovered in your games? Head over to the Bug Reporting section of the PCSX2 forums, to the PCSX2 Discord, or to the GitHub issues section. Also check out our Issue reporting guide 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
• Want to improve the PCSX2 wiki? Here is how to contribute

Question 4: Is PCSX2 ready to run out-of-the-box? Copy Section

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.

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 Copy Chapter

Question 5: What are the PC requirements to use PCSX2? Copy Section

Minimum

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, Forum and CPU light games: Forum

Recommended

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 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

Heavy

Question 6: How many CPU cores can PCSX2 use? Copy Section

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? Copy Section

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? Copy Section

No. PCSX2 does not use or require multi-GPU.

Question 9: How do I check if a game is playable? Copy Section

The PCSX2 website has a compatibility list with every game that has been tested.

Question 10: Do PS1 (PSX) games work on PCSX2? Copy Section

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 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? Copy Section

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 are very helpful for finding the exact change that caused a regression.

Question 12: Why is PCSX2 slow? Copy Section

The PlayStation 2 is a complex console, and this substantially raises the PC requirements to emulate it at full speed accurately. This forum thread 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? Copy Section

You have to dump the BIOS files from your PlayStation 2 console. There is a BIOS dumper tool available on the PCSX2 website 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? Copy Section

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? Copy Section

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.

Question 16: How do I play a game? Copy Section

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? Copy Section

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? Copy Section

See the build guide.

Question 19: When will the next version be released? Copy Section

It will be released when it is ready. Please don't waste your time and ours asking when.

PCSX2 Configuration Copy Chapter

Question 20: How do I configure PCSX2? Copy Section

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? Copy Section

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? Copy Section

• 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? Copy Section

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? Copy Section

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 to see if your game needs an alternate setting, or check the PCSX2 Forums to see if anyone else has posted about it there.

Question 25: What are PCSX2 plugins? Copy Section

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? Copy Section

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? Copy Section

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 Copy Chapter

BIOS Dumping Guides Copy Section

• pgert's guide to BIOS and memory card tools
• One of the original BIOS dumping guides, originally from ngemu

Memory Card and Save File Guides Copy Section

• pgert's guide to BIOS and memory card tools
• An older guide on merging GameFAQs saves into PCSX2 memory cards. 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,

PCSX2 Cheats and Patches (PNACH) Copy Section

• The currently accepted master-guide to cheats and patches.
• The original guide, outdated.

PCSX2 with Netplay Support Copy Section

• The latest Netplay fork of PCSX2.

Pcsx2 Docs Gamedb Schema.Json (`pcsx2/Docs/gamedb-schema.json`) Copy Section

{
"$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`) Copy Section

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 Copy Chapter

The first time you launch PCSX2, you will be prompted with a First Time Configuration wizard.

Language Selection Copy Section

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.

BIOS Selection Copy Section

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 Copy Chapter

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 Copy Section

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 if these solutions do not help.

--- METRICS ---

• Files Extracted: 32
• Estimated Token Budget: ~59292 tokens
• Canonical Reference: https://codewiki.google/github.com/PCSX2/pcsx2