A Rust and egui based front-end for the SwanStation PS1 Libretro core
  • C++ 58.4%
  • C 36.7%
  • Rust 2.2%
  • HLSL 0.7%
  • GLSL 0.6%
  • Other 1.2%
Find a file
LibretroAdmin 65d02fd1cc core, common/vulkan: lazy-fault non-batch PSOs
Symmetry pass for the Vulkan backend matching the D3D12 fix.

# What changed

Three threads now share the lazy-fault PSO matrix without
serialising on a single compile mutex:

  * common/vulkan/shader_cache: ShaderCache is now thread-safe.
    Two internal mutexes:
      - m_shader_cache_mutex covers the SPIR-V index
        (unordered_map), the blob file, and the index file. NOT
        held across ShaderCompiler::CompileShader, so two threads
        compiling different shaders run truly in parallel. Two
        threads compiling the SAME shader both run glslang; the
        double-check under the lock picks whichever publishes
        first and the loser's SPIR-V is discarded.
      - m_pipeline_cache_mutex serialises the VkPipelineCache.
        Per Vulkan 1.0 spec, the pipelineCache parameter to
        vkCreateGraphicsPipelines is in the host-synchronised
        parameter list - the application must guarantee no
        concurrent use of the same VkPipelineCache. Exposed via
        PipelineCacheMutex() for callers that need to honour the
        contract.

  * core/gpu_hw_vulkan: non-batch pipelines (VRAM fill / copy /
    write / update depth / readback, display, downsample) and
    their shared fullscreen-quad / UV-quad vertex shaders are now
    lazy-fault helpers, same shape as the D3D12 backend's
    GetVRAMFillPipeline / GetDisplayPipeline / etc. Each helper
    runs glslang lock-free, takes PipelineCacheMutex briefly
    around vkCreateGraphicsPipelines, and writes the slot.
    Twelve sites that bound the raw member pipelines via
    vkCmdBindPipeline now go through the helpers.

  * core/gpu_hw_vulkan: the batch helpers (GetBatchFragmentShader,
    GetBatchPipeline) no longer hold m_batch_shader_mutex across
    the slow operations. Each runs glslang + vkCreateShaderModule
    lock-free, takes PipelineCacheMutex around the
    vkCreateGraphicsPipelines call, then takes m_batch_shader_mutex
    BRIEFLY to publish under a double-check - the mutex is now a
    publish-step lock only, scoped to a slot.store + race-loser
    vkDestroy*. Window measured in microseconds instead of the
    previous hundreds of milliseconds.

# Why this matters (Vulkan-specific reasoning)

In the pre-fix design, m_batch_shader_mutex covered the entire
compile-and-publish sequence, including the glslang -> SPIR-V
step. After a UpdateSettings change (e.g. texture filter,
resolution scale) the precompile worker would hold the mutex
across each ~150-300 ms glslang compile of the heavier shaders,
and every concurrent main-thread DrawBatchVertices stalled
behind it for the full duration. The runloop never made forward
progress until the worker finished the entire 2160-entry batch
matrix - same user-visible multi-second hang the D3D12 backend
had.

Unlike D3D12, Vulkan 1.0 cannot drop the lock entirely:
vkCreateGraphicsPipelines requires external sync on the
pipelineCache parameter (D3D12's CreateGraphicsPipelineState
is thread-safe by Microsoft's documentation, no equivalent
guarantee in Vulkan 1.0). The
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT flag from
Vulkan 1.3 would let us elide this, but SwanStation targets
VK_API_VERSION_1_0, so the lock around vkCreateGraphicsPipelines
is mandatory.

The win is still substantial because the EXPENSIVE step -
glslang -> SPIR-V translation, which has the D3DCompile-style
optimiser cost characteristic - now runs lock-free across
threads. vkCreateGraphicsPipelines itself is mostly the driver
enqueueing SPIR-V -> GPU-ISA work onto its own background
threads; the caller-thread time inside that call is short. So
PipelineCacheMutex is held for tens of milliseconds per
compile, not hundreds.

# Lazy main-thread pre-fill (mandatory)

Same pattern as D3D12: in Lazy mode, after the non-batch
upfront block (which is now empty - all non-batch PSOs are
lazy too), the main thread pre-fills every non-batch helper
before spawning the worker. Without this, the worker could
hold PipelineCacheMutex through the batch matrix walk and the
runloop's first FillVRAM / UpdateDisplay would starve on
non-FIFO Windows std::mutex.

# Behaviour summary (same shape as D3D12 commit)

  * Disabled: CompilePipelines builds only the two batch vertex
              shaders. All other PSOs faulted in on first draw.
              ~150 KB shader-cache + ~150 KB pipeline-cache
              footprint after a session.
  * Lazy:     CompilePipelines builds the two batch vertex
              shaders + all non-batch PSOs via the main-thread
              pre-fill, then spawns the worker to walk the
              batch matrix in the background. Gameplay starts
              instantly; worker fills slots opportunistically.
              ~5 MB cache footprint when worker finishes.
  * Enabled:  CompilePipelines builds the two batch vertex
              shaders + every batch shader-module + every PSO
              upfront via the same helpers (so the progress bar
              ticks per pipeline). Original ~35 s upfront pause.
              ~5 MB cache footprint immediately.

# Files touched

  * src/common/vulkan/shader_cache.h: declare
    m_shader_cache_mutex, m_pipeline_cache_mutex, add
    PipelineCacheMutex() accessor.
  * src/common/vulkan/shader_cache.cpp: scope-narrow
    m_shader_cache_mutex around index + file I/O in
    GetShaderSPV; add the double-check + publish pattern to
    CompileAndAddShaderSPV.
  * src/core/gpu_hw_vulkan.h: declare 13 lazy helpers, two
    member shader-module slots for the shared
    fullscreen-quad / UV-quad vertex shaders.
  * src/core/gpu_hw_vulkan.cpp: implement the helpers, gate the
    upfront non-batch block on precompile_sync, add the
    main-thread pre-fill for Lazy, swap 12 draw-path bindings
    onto the helpers, update DestroyPipelines to tear down the
    member shaders.

The 25 retro_* libretro exports are preserved. .so size is
unchanged versus master.
2026-05-15 03:49:01 +02:00
CMakeModules Remove unused files 2023-03-25 17:43:35 +01:00
dep Make OpenBIOS a built-in fallback. 2026-03-28 10:43:30 +00:00
src core, common/vulkan: lazy-fault non-batch PSOs 2026-05-15 03:49:01 +02:00
.clang-format clang-format: Enable brace wrapping after case label 2020-01-24 14:49:43 +10:00
.gitattributes Initial commit 2019-09-11 14:00:42 +10:00
.gitignore Sync Android strings 2021-07-17 20:14:40 +10:00
.gitlab-ci.yml Merge pull request #167 from cscd98/webos-ci 2026-04-10 05:12:17 +02:00
CMakeLists.txt build: add MSB_FIRST opt-in flag for big-endian hosts 2026-05-08 00:32:03 +02:00
libretro.osx.def libretro: add static Makefile.libretro build 2026-05-07 21:32:02 +02:00
LICENSE Initial commit 2019-09-11 14:00:42 +10:00
link.T libretro: add static Makefile.libretro build 2026-05-07 21:32:02 +02:00
Makefile.libretro Makefile.libretro: compile D3D12 backend by default on Windows 2026-05-15 01:13:18 +02:00
README.md Documentation OpenBIOS usage in the README. 2026-04-02 10:46:10 +01:00
TODO Update TODO (#132) 2025-01-17 16:28:45 +01:00

SwanStation - PlayStation 1, aka. PSX Emulator

Features | System Requirements | Disclaimers

SwanStation is a hard fork and open-source Libretro core implementation of DuckStation, which is an emulator of the Sony PlayStation(TM) console, focusing on playability, speed, and long-term maintainability. The goal is to be as accurate as possible while maintaining performance suitable for low-end devices. "Hack" options are discouraged, the default configuration should support all playable games with only some of the enhancements having compatibility issues.

A "BIOS" ROM image can be used, but is not required. You can use an image from any hardware version or region, although mismatching game regions and BIOS regions may have compatibility issues. A ROM image is not provided with the emulator for legal reasons, you should dump this from your own console using Caetla or other means. If no ROM image is provided, OpenBIOS will be used instead.

Features

SwanStation features include:

  • CPU Recompiler/JIT (x86-64, armv7/AArch32 and AArch64)
  • Hardware (D3D11, OpenGL, Vulkan) and software rendering
  • Upscaling, texture filtering, and true colour (24-bit) in hardware renderers
  • PGXP for geometry precision, texture correction, and depth buffer emulation
  • Adaptive downsampling filter
  • Post processing shader chains
  • "Fast boot" for skipping BIOS splash/intro
  • Save state support
  • Supports bin/cue images, raw bin/img files, MAME CHD, single-track ECM, MDS/MDF, and unencrypted PBP formats.
  • Direct booting of homebrew executables
  • Direct loading of Portable Sound Format (psf) files
  • Digital and analog controllers for input (rumble is forwarded to host)
  • Namco GunCon lightgun support (simulated with mouse)
  • NeGcon support
  • Emulated CPU overclocking
  • Multitap controllers (up to 8 devices)
  • RetroAchievements
  • Automatic loading/applying of PPF patches

System Requirements

  • A CPU faster than a potato. But it needs to be x86_64, AArch32/armv7, or AArch64/ARMv8, otherwise you won't get a recompiler and it'll be slow.
  • For the hardware renderers, a GPU capable of OpenGL 3.1/OpenGL ES 3.0/Direct3D 11 Feature Level 10.0 (or Vulkan 1.0) and above. So, basically anything made in 2013 or later.

Region detection and BIOS images

By default, SwanStation will emulate the region check present in the CD-ROM controller of the console. This means that when the region of the console does not match the disc, it will refuse to boot, giving a "Please insert PlayStation CD-ROM" message. SwanStation supports automatic detection disc regions, and if you set the console region to auto-detect as well, this should never be a problem.

The region checking can be disabled in the console options tab. This is the only way to play unlicensed games or homebrew which does not supply a correct region string on the disc, aside from using fastboot which skips the check entirely.

Mismatching the disc and console regions with the check disabled is supported, but may break games if they are patching the BIOS and expecting specific content.

LibCrypt protection and SBI files

A number of PAL region games use LibCrypt protection, requiring additional CD subchannel information to run properly. libcrypt not functioning usually manifests as hanging or crashing, but can sometimes affect gameplay too, depending on how the game implemented it.

For these games, make sure that the CD image and its corresponding SBI (.sbi) file have the same name and are placed in the same directory. SwanStation will automatically load the SBI file when it is found next to the CD image.

For example, if your disc image was named Spyro3.cue, you would place the SBI file in the same directory, and name it Spyro3.sbi.

Tests

  • Passes amidog's CPU and GTE tests in both interpreter and recompiler modes, partial passing of CPX tests

Disclaimers

"PlayStation" and "PSX" are registered trademarks of Sony Interactive Entertainment Europe Limited. This project is not affiliated in any way with Sony Interactive Entertainment.