TsundereStation/data/shaders/d3d12
LibretroAdmin 443a2a130b core/d3d12: pre-bake the copy/blit pixel shader
Next single-variant non-batch shader in the D3D12 pre-bake arc,
on top of fullscreen_quad_vs (dd54a73 + 77b255f). Picks the
copy/blit fragment shader (GenerateCopyFragmentShader -> bound
in GetCopyPipeline, used for full-frame blits during display
presentation / downscaling).

Why this one and not vram_copy / vram_update_depth / vram_fill /
vram_read / display - which were the other candidates on the
shortlist:

  * vram_update_depth: has an MSAA #ifdef split inside the body
    (LOAD_TEXTURE_MS vs LOAD_TEXTURE) plus a declare_sample_id
    in DeclareFragmentEntryPoint that depends on UsingMSAA(). So
    2 variants minimum, more once we account for the MSAA sample
    count.
  * vram_copy: has a PGXP_DEPTH define, plus uses VRAM_SIZE which
    is compile-time-baked from m_resolution_scale * VRAM_WIDTH/
    HEIGHT via the non-batch WriteCommonFunctions path. 2x
    pgxp_depth times ~5 resolution scale values minimum.
  * vram_fill: PGXP_DEPTH x wrapped x interlaced plus VRAM_SIZE
    via the same compile-time-bake path. 4x variants minimum,
    more after multiplying by resolution scale.
  * vram_read: VRAM_SIZE / RESOLUTION_SCALE bake-in via
    WriteCommonFunctions; the inner box-filter loop uses
    RESOLUTION_SCALE directly as the loop bound, so the variant
    count is one per scale value (5+).
  * display: depth_24bit x interlace_mode x smooth_chroma x
    UsingMSAA x RESOLUTION_SCALE - the multi-variant family with
    the biggest cost.

Each of the above hits one of two structural issues that the
infrastructure doesn't address yet:

  1. RESOLUTION_SCALE / VRAM_SIZE are baked in compile-time for
     non-batch shaders via WriteCommonFunctions's
     batch_uniform_buffer=false path. The cbuffer-routed batch
     path (post-7b575a3) only applies to batch shaders. Migrating
     a non-batch shader that references these constants requires
     either one .inc per resolution scale value, or a refactor
     that lets non-batch shaders read u_resolution_scale from the
     cbuffer too.
  2. The MSAA dimension multiplies every shader that calls
     LOAD_TEXTURE_MS in some branch.

ShaderGen::GenerateCopyFragmentShader (NOT
GPU_HW_ShaderGen::GenerateVRAMCopyFragmentShader - this is the
plain blit one declared in shadergen.h, not the VRAM-coords
copy in gpu_hw_shadergen.cpp) sidesteps all of this:

  * No WriteCommonFunctions call - so no RESOLUTION_SCALE, no
    VRAM_SIZE, no MULTISAMPLES bake-in.
  * No MSAA branch - takes a single Texture2D, not Texture2DMS.
  * No #define-controlled variants - the source string is
    identical on every call.
  * cbuffer-routed source rect (u_src_rect float4) - all runtime
    state lives in the UBO, none baked.

So one pre-baked variant covers every caller. Same shape as
fullscreen_quad_vs.

Files in this patch:

* data/shaders/d3d12/copy.ps.hlsl - standalone HLSL, ~16 lines,
  native HLSL syntax (no shadergen prelude, no aliases). cbuffer
  UBOBlock at register(b0), Texture2D samp0 at register(t0) +
  SamplerState samp0_ss at register(s0), one TEXCOORD0 input,
  one SV_Target0 output. Same source rect math as the original
  generated shader.

* src/common/d3d12/embedded_dxbc/copy_ps.inc - autogenerated by
  tools/regen_d3d12_dxbc.py /T ps_5_0 /E main /O3. Generated in
  this submission environment via Wine's d3dcompiler_47.dll
  through the fxc_lite shim (see 77b255f for the full toolchain
  setup). 808 bytes of valid DXBC (magic 0x43425844 / "DXBC",
  four chunks: ISGN / OSGN / SHEX / STAT).

* src/common/d3d12/embedded_shaders.h - extern declarations for
  k_copy_ps[] and k_copy_ps_size_bytes added below the existing
  fullscreen_quad_vs pair. Same comment format - documents the
  shader's role and the no-state-dependency rationale.

* src/common/d3d12/embedded_shaders.cpp - second #include line
  for embedded_dxbc/copy_ps.inc inside the namespace block.
  Pattern matches what subsequent migrations will follow.

* src/core/gpu_hw_d3d12.cpp - GetCopyPipeline body updated:
  - The ComPtr<ID3DBlob> fs = m_shader_cache.GetPixelShader(
    m_shadergen->GenerateCopyFragmentShader()) + null check
    replaced with a const D3D12_SHADER_BYTECODE fs = { ... }
    aggregate-init over the embedded blob.
  - The if (!m_shadergen) check is dropped - GetCopyPipeline
    no longer has any m_shadergen dependency. Other state
    (root signature, context, shader cache, mutex) was already
    initialised earlier than m_shadergen in the lifecycle, so
    removing the m_shadergen check doesn't open a 'called too
    early' window for this helper.
  - gpbuilder.SetPixelShader(fs.Get()) becomes
    gpbuilder.SetPixelShader(fs.pShaderBytecode,
                             static_cast<uint32_t>(fs.BytecodeLength))
    matching the existing SetVertexShader call form a few
    lines above. (Cleanup: a D3D12_SHADER_BYTECODE& overload
    on SetVertexShader / SetPixelShader in d3d12/util.h would
    elide the verbose unpack at all call sites - deferred to
    a follow-up patch so this one stays focused on the shader
    migration.)

Progress unit count unchanged. GetCopyPipeline still costs one
progress.Increment call in the precompile_sync block at the
'copy/blit (1)' entry of the 4 + 2 + 2 + 1 + 1 + 6 + 1 = 17
breakdown - the embedded shader removes the D3DCompile work,
but the ID3D12Device::CreateGraphicsPipelineState call (the
PSO compile) is what the progress tick actually corresponds to,
and that still happens.

Cost / behaviour:
  - Cold boot, shader_precompile_mode = Enabled: one fewer
    D3DCompile per first-touch of GetCopyPipeline (which is hit
    once per CompilePipelines pass). Combined with
    fullscreen_quad_vs, that's two non-batch shaders off the
    D3DCompile path. The bulk of the cold-boot ~1 min cost is
    still in the batch matrix (1164 cells) - this migration
    chips at a single non-batch unit, but it's the right next
    step structurally because it validates the .ps.hlsl side
    of the pipeline (fullscreen_quad_vs only validated .vs).
  - Lazy mode: same delta, on first lazy-fault of the copy
    pipeline.
  - Disabled: same delta, on first GetCopyPipeline call from
    the runloop (presentation copy / downscale).
  - Runtime: no behaviour change. The pre-baked DXBC binds at
    PSO creation; presentation copies / downscaling renders
    identically.

Failure modes to watch for:
  - If Wine's d3dcompiler produces semantically different DXBC
    from Microsoft's fxc.exe for this specific shader (very
    unlikely given the simplicity - one texture sample, no
    branching, no flow control), the blit would render
    incorrectly. Visible immediately as a wrong / blank
    presentation. Easy to spot.
  - If the .inc file gets out of sync with copy.ps.hlsl (e.g.
    someone edits the .hlsl without re-running the regen
    script), the embedded blob would compile against the old
    shader source. The autogen header comment in the .inc
    documents the source it was generated from, and the regen
    script is idempotent (re-running it on an unchanged .hlsl
    produces byte-identical output), so getting the two back
    in sync is just `python3 tools/regen_d3d12_dxbc.py`.

Test:
  - Build under USE_D3D12=1 succeeds.
  - Cold boot under shader_precompile_mode = Enabled. Progress
    bar reaches 100% at 17 non-batch units (unchanged). The
    copy/blit pipeline ticks the same as before; its PSO is
    built with the embedded PS blob.
  - Presentation / downscaling render correctly - GetCopyPipeline
    is called at presentation time from the host display layer.
    If the embedded PS is wrong, the framebuffer presents wrong
    on the first frame.
  - Toggle a non_dim setting (multisamples) to fire the full-
    flush branch. m_copy_pipeline is Reset() in DestroyPipelines;
    next CompilePipelines pass re-binds the embedded blob.
  - Toggle chroma_smoothing for the partial-flush branch -
    GetCopyPipeline isn't reached (only display pipelines clear),
    embedded blob undisturbed.

Next in the arc: a util.h cleanup adding a
SetVertexShader/SetPixelShader(D3D12_SHADER_BYTECODE&) overload
so the .pShaderBytecode + static_cast<uint32_t>(.BytecodeLength)
boilerplate disappears from call sites. After that, the
RESOLUTION_SCALE cbuffer refactor for non-batch shaders opens
up vram_copy / vram_update_depth / vram_fill / vram_read - the
last single-variant or near-single-variant non-batch shaders
before the batch matrix takes the rest of the arc.
2026-05-18 20:22:17 +02:00
..
copy.ps.hlsl core/d3d12: pre-bake the copy/blit pixel shader 2026-05-18 20:22:17 +02:00
fullscreen_quad.vs.hlsl core/d3d12: pre-bake the fullscreen-quad vertex shader 2026-05-18 19:40:13 +02:00
README.md core/d3d12: scaffolding for pre-baked DXBC blobs 2026-05-18 09:14:52 +02:00

D3D12 shader sources (pre-baked DXBC)

This directory holds the HLSL sources for shaders used by the D3D12 backend that have been moved off the runtime ShaderGen path. Each .hlsl file here has a matching pre-compiled DXBC blob checked in to src/common/d3d12/embedded_dxbc/.

Why this exists

Historically the D3D12 backend generated HLSL at runtime via src/core/shadergen.cpp and src/core/gpu_hw_shadergen.cpp, then handed the text to D3DCompile (the in-process HLSL -> DXBC compiler from d3dcompiler_47.dll) to produce a DXBC blob for each PSO. On a cold shader cache, walking the 1164-cell batch pipeline matrix in precompile_sync mode takes on the order of one minute, which is the worst entry in the post-dim-cache cost matrix (see the cost-matrix comments in 10c53b8, 57ac62e, and the patches that followed). The runtime cache hides this on warm boots, but cold boots and shader cache invalidations re-pay the full per-cell D3DCompile cost every time the user changes a setting that hits the full-flush branch.

Pre-baking the DXBC removes:

  • per-launch HLSL compilation stall on shader cache misses,
  • a class of "stale cache after d3dcompiler_47.dll version drift" failures,
  • the implicit dependency on D3DCompile being available at runtime for the cells that have been pre-baked.

The OpenGL / OpenGL ES / D3D11 / Vulkan backends still use the runtime ShaderGen path; only the D3D12 backend reads from the embedded DXBC. (The Vulkan equivalent of this infrastructure lives at data/shaders/vulkan/ / src/common/vulkan/embedded_spirv/ / tools/regen_vulkan_spirv.py; this directory is the mirror.)

Build-time constraint

The core build (Makefile.libretro and src/common/CMakeLists.txt) must never invoke fxc.exe or any other external shader compiler. The .inc files under src/common/d3d12/embedded_dxbc/ are checked into the repository and compiled like any other C++ source. The tools/regen_d3d12_dxbc.py helper exists for contributors who edit the .hlsl sources in this directory; it is not part of the build.

Regenerating the DXBC blobs

After editing a .hlsl file here, run:

python3 tools/regen_d3d12_dxbc.py

This invokes fxc.exe (Shader Model 5.0, /O3, /E main) on each .hlsl file and rewrites the matching .inc under src/common/d3d12/embedded_dxbc/. Both the .hlsl and the regenerated .inc must be committed together so the two stay in sync.

fxc.exe ships with the Windows 10 SDK and is not invoked by the core build. On Linux, run the script under Wine - it will look for fxc.exe in the standard SDK install path under $WINEPREFIX/drive_c/Program Files (x86)/Windows Kits/10/bin/<version>/x64/fxc.exe, or you can pass --fxc PATH explicitly. The --wine PATH flag lets you point at a specific wine binary if wine isn't on PATH.

Filename convention

Stage is encoded in the suffix:

  • .vs.hlsl -> vertex shader (compiled as vs_5_0)
  • .ps.hlsl -> pixel shader (compiled as ps_5_0)
  • .cs.hlsl -> compute shader (compiled as cs_5_0)
  • .gs.hlsl -> geometry shader (compiled as gs_5_0)

The _5_0 shader model targets D3D_FEATURE_LEVEL_11_0, matching the runtime baseline of the D3D12 backend (see the shared compile path in src/common/d3d11/shader_compiler.cpp which both D3D11 and D3D12 used prior to the pre-bake migration).

Template variants

Shaders that need multiple pre-baked variants (e.g. one per BatchRenderMode or per GPUTextureFilter) are listed in the TEMPLATE_VARIANTS dict at the top of tools/regen_d3d12_dxbc.py. Each entry maps an .hlsl filename to the list of (variant_suffix, [/D defines]) tuples that the regen script should produce.

If you add a template variant to the dict, add the matching extern declaration to src/common/d3d12/embedded_shaders.h AND the matching slot lookup to src/common/d3d12/embedded_shaders.cpp - the index ordering at the runtime call site must match the order in the dict so the correct blob gets bound at PSO-creation time.