A Rust and egui based front-end for the SwanStation PS1 Libretro core
  • C++ 58.5%
  • C 36.8%
  • Rust 2%
  • HLSL 0.7%
  • GLSL 0.6%
  • Other 1.2%
Find a file
LibretroAdmin 116a70eae2 core: route PGXP_DEPTH through the batch UBO for the FS
Companion to 49c0f82 (VS-side PGXP_DEPTH routing). The FS-side
routing converts SV_Depth from a per-variant signature decision
to an always-declared output, with a single runtime-branch write
at the end of main() picking the right depth expression based on
the u_pgxp_depth cbuffer scalar (added to BatchUBOData in
49c0f82 and already populated by Initialize / Reset /
UpdateHWSettings).

C++ shadergen path only this commit (D3D11 / D3D12 / OpenGL).
Vulkan FS templates still have PGXP_DEPTH as a -D variant axis
and a follow-up commit will collapse it across all five FS
templates (parallel to the UV_LIMITS Nearest-FS-routing
follow-up pattern). m_pgxp_depth_buffer stays in
shader_source_changed for now because Vulkan still needs the
rebuild to switch pre-baked SPIR-V variants and because the
PSO depth comparison func (LESS_EQUAL vs GREATER_EQUAL) still
depends on m_pgxp_depth_buffer at PSO build time across all
backends.

What changes in the shadergen:

  DefineMacro(ss, "PGXP_DEPTH", m_pgxp_depth);
  -> dropped from the FS prelude. m_pgxp_depth at shadergen
  ctor capture is now unused for the batch FS body / signature.
  (The member field stays - the VS still captures it for the
  body comment / documentation, the constructor still accepts
  it because the gpu_hw_*.cpp shadergen instantiations still
  pass it, and the vram_write / vram_copy / vram_fill non-
  batch shaders below in the same file still use PGXP_DEPTH as
  a -D macro on their own variant matrices.)

  DeclareFragmentEntryPoint(ss, ..., !m_pgxp_depth, ...)
  -> DeclareFragmentEntryPoint(ss, ..., true, ...)
  Both call sites (textured and untextured arms of the batch
  FS) unconditionally request SV_Depth declaration.

  FS body o_depth writes: four `#if !PGXP_DEPTH / o_depth =
  oalpha * v_pos.z / #endif` blocks inside the four
  transparency arms (TRANSPARENCY + TEXTURED semitransparent,
  TRANSPARENCY + TEXTURED opaque, TRANSPARENCY-only-untextured,
  non-TRANSPARENCY) collapse to a single unconditional write
  at the end of main():

    o_depth = (u_pgxp_depth != 0u) ? v_pos.z : (oalpha * v_pos.z);

  All four old sites wrote the same expression with the same
  operand values in scope, so hoisting to a single end-of-
  function site is value-equivalent. The discards in the
  TRANSPARENCY_ONLY_OPAQUE / _TRANSPARENT arms above end the
  FS before the o_depth write runs, just as they did
  pre-routing.

Why the ternary is correct:

  u_pgxp_depth != 0 (PGXP-depth mode):
    The VS computes pos_z from a_pos.w (PGXP-replayed depth)
    and writes it through v_pos.z. The rasterizer
    interpolates it. Writing v_pos.z back to o_depth is a
    pass-through that produces the same depth value the
    pre-routing PGXP-on path got from omitting SV_Depth
    entirely (rasterizer-interpolated depth goes straight to
    the depth buffer).

  u_pgxp_depth == 0 (legacy mask-bit mode):
    The VS computes pos_z from a_pos.z (mask-bit Z). oalpha
    is 0 or 1 in this mode (set by the C++ side based on
    whether the pixel should mask). oalpha * v_pos.z is
    either 0 (mask off) or v_pos.z (mask on) - the same
    encoding the pre-routing PGXP-off path wrote.

Performance trade:

  Pre-routing, only the PGXP-on batch FS variants retained
  early-Z TEST. Every PGXP-off variant lost it to SV_Depth
  declaration, and every batch FS variant (both PGXP modes)
  lost early-Z WRITEBACK to the discard keyword's static
  presence (texture-transparent discard plus the
  u_interlacing discard added in eb42ffb). Post-routing, all
  batch FS variants lose early-Z TEST.

  This is the same character of trade Lib accepted for
  earlier cbuffer-routing commits (the discard-driven
  WRITEBACK loss in eb42ffb, called out in the
  GenerateBatchFragmentShader comment around the
  u_interlacing branch). The PGXP-on path was the last
  remaining variant with early-Z TEST; this commit takes it.

  For PSX content on modern GPUs:
    - Native framebuffer is 1024x512 = ~0.5 Mpix. At 16x
      resolution scale that's ~134 Mpix. Even with 5x
      overdraw that's ~670 Mpix of FS work, well within
      sub-millisecond throughput on a 5090.
    - PSX overdraw is low. The original hardware can't
      handle much, so games are designed around 1-3x typical
      / 5-10x in particle-heavy moments, not the 20-50x
      modern engines see.
    - PSX renders are typically painter's-algorithm sorted
      back-to-front (for transparency correctness). Front-
      to-back sort + early-Z is the configuration where
      early-Z TEST pays off - PSX deliberately does the
      opposite to be sort-correct.
    - The depth buffer in legacy mode is mask-bit storage,
      not perspective depth. Hi-Z hierarchical compression
      can't compress essentially-random values, so even when
      early-Z TEST was active, Hi-Z wasn't doing much.

  Net: the early-Z TEST loss is theoretical; on the target
  hardware it is sub-noise. Same character as the prior
  cbuffer-routing trades.

PSO depth-comp dependency is OUTSIDE this commit:

  Per gpu_hw_d3d12.cpp:1317-1319, the PSO depth comparison
  func is set at PSO build time:
    depth_test ? (m_pgxp_depth_buffer ? LESS_EQUAL
                                       : GREATER_EQUAL)
               : ALWAYS;
  m_pgxp_depth_buffer flips therefore still require PSO
  rebuilds to swap the comparison func. The FS bytecode is
  now invariant across the flip (cache-served) but the PSO
  cache key still includes m_pgxp_depth_buffer indirectly
  via the depth-comp field. This commit does not unify the
  depth-comp func across PGXP modes - that would require
  either always-using one comparison func and inverting the
  depth values in the other mode (a meaningful algorithmic
  change) or making depth-comp a matrix dim (which doubles
  m_batch_pipelines count). Neither belongs in a routing
  commit. The eventual decision: most likely keep depth-comp
  as a PSO-state dep on m_pgxp_depth_buffer and accept that
  PGXP toggles re-assemble PSOs from cached FS blobs.

Pre-bake variant count, cumulative arc progress:

  Pre-arc:               75 264
  After DITHERING:       37 632
  After INTERLACING:     18 816
  After PGXP-VS:         no change (FS pre-bake unaffected)
  After UV_LIMITS:        9 408
  After PGXP-FS (this):   4 704

  Remaining axes that would need decision before pre-bake:
    multisamples           x 6  (kept as a variant axis)
    per_sample_shading     x 2  (decision pending)
    disable_color_perspective x 2  (decision pending)

  If both per_sample / dcp collapse via forced-always
  settings: 4704 / 4 = 1176. That is the rough target the
  pre-bake commits will aim at.

Cost matrix delta (D3D12):

  PGXP toggle mid-session (m_pgxp_depth_buffer flips):
    Pre-commit:  FS bytecode varies across the flip, so
                 shader_source_changed fires the full
                 ~252 FS blob + ~2520 PSO rebuild. With
                 disk shader cache populated, the FS
                 compiles are cache hits and the cost is
                 ~2520 PSO assembly calls.
    Post-commit: FS bytecode is invariant. The full
                 rebuild path STILL fires (PSO depth-comp
                 swap), but every FS lookup is now a
                 byte-identical hash hit. PSO assembly
                 is unchanged. Net: 252 fewer D3DCompile
                 calls on a cold cache (was zero on a
                 warm cache, so no change there). Pre-bake
                 variant count halved.

  Steady-state runtime cost:
    + one runtime branch + one MUL in every batch FS
      invocation. The branch is uniform across the warp
      (u_pgxp_depth is a cbuffer scalar) so it costs a
      single divergent-free predicated select on modern
      hardware. Sub-microsecond at the framebuffer sizes
      PSX rendering produces.

Cross-backend impact:

  D3D11 / D3D12 / OpenGL: get the routed FS bytecode
  starting this commit. PSO depth-comp dep on
  m_pgxp_depth_buffer unchanged.

  Vulkan: untouched - its batch FS templates live in
  data/shaders/vulkan/batch_*.frag.glsl and have their own
  PGXP_DEPTH -D variant axis. Routing those is a follow-up
  commit (parallel to the UV_LIMITS Nearest FS routing
  pattern: add u_pgxp_depth to the Vulkan FS UBO, drop the
  #if defined(PGXP_DEPTH) guards, regen 5 FS template
  variant sets).

Test:
  - Build: D3D11 / D3D12 / OpenGL compile. Vulkan
    untouched.
  - Default render (PGXP off): u_pgxp_depth = 0, FS
    ternary picks oalpha * v_pos.z (mask-bit-depth-encode).
    PSO depth comp is GREATER_EQUAL (m_pgxp_depth_buffer
    is false). Output identical to pre-commit.
  - Toggle PGXP-depth-buffer on: m_pgxp_depth_buffer flips,
    shader_source_changed fires, the FS / PSO matrix
    rebuilds. With disk shader cache warmed, the FS blobs
    are cache hits (byte-identical pre vs post commit, AND
    pre vs post PGXP toggle); PSO assembly runs with the
    new LESS_EQUAL depth comp. u_pgxp_depth = 1, FS
    ternary picks v_pos.z (pass-through). Output identical
    to pre-commit PGXP-on state.
  - Specific titles to validate the mask-bit-depth-encode
    path:
      * Crash 1/2/3 - heavy semitransparent particle work
        relies on mask-bit encoding for correct depth
        masking. Any visual difference vs pre-commit
        would show up as wrong-Z particle layering.
      * Final Fantasy VII/VIII/IX combat backgrounds -
        the framebuffer-effects layer uses the mask bit
        for compositing. Visual sanity at 4-16x resolution
        scale.
      * Silent Hill 1 - heavy use of the mask bit for the
        fog plane. PGXP off baseline.
  - Specific titles for the PGXP-on pass-through:
      * Tekken 3 / Soul Blade - PGXP-on textured polygons.
        Any FS depth-writing error would show up as
        z-fighting on co-planar stage geometry.
      * Tomb Raider 1/2 - PGXP-corrected world geometry,
        polygon-level visibility.

Next:
  - Vulkan FS PGXP_DEPTH routing across all 5 templates
    (parallel structure to the UV_LIMITS Nearest FS
    routing).
  - per_sample / dcp collapse decisions.
  - Pre-bake the resulting D3D12 FS matrix.
2026-05-19 03:28:19 +02:00
CMakeModules Remove unused files 2023-03-25 17:43:35 +01:00
data/shaders core/vulkan: route the Nearest FS UV_LIMITS axis to a cbuffer scalar 2026-05-19 03:07:27 +02:00
dep dep, common/vulkan, core, build: remove dep/glslang and the Vulkan ShaderCompiler infrastructure 2026-05-18 02:21:53 +02:00
src core: route PGXP_DEPTH through the batch UBO for the FS 2026-05-19 03:28:19 +02:00
tools core/vulkan: route the Nearest FS UV_LIMITS axis to a cbuffer scalar 2026-05-19 03:07:27 +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 core/d3d12: scaffolding for pre-baked DXBC blobs 2026-05-18 09:14:52 +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.