You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I added a repo-owned D3D12 Metal SDK under tools/d3d12-metal-sdk/. This is now the main development and validation surface for MetalSharp's D3D12, DXMT, and Metal work.
The goal is simple: D3D12 support should be evidence-driven. Before a feature is advertised, merged, or used as the basis for game debugging, it should be backed by a contract, a probe, a repeatable script, or an explicit unsupported/risky-stub ledger entry.
What The SDK Is
The SDK is a local validation harness for D3D12-on-Metal work through Wine-compatible DXMT runtimes.
It includes:
Contract files in tools/d3d12-metal-sdk/contracts/
Windows probe executables built from tools/d3d12-metal-sdk/probes/
Runtime staging and preflight scripts in tools/d3d12-metal-sdk/scripts/
Generated probe results in tools/d3d12-metal-sdk/results/
External tooling bootstrap support under tools/d3d12-metal-sdk/external/
MetalSharp is one runtime profile, but the probes are intentionally normal Windows executables. They can run against the MetalSharp runtime, standalone Wine prefixes, DXMT development prefixes, and future host integrations.
Current Capability Truth
The current D3D12 posture is intentionally conservative:
DXIL-to-MSL is contract-gated and proven.
DXIL semantics are contract-gated and proven.
Reflection ABI is contract-gated and proven.
Descriptor ABI is contract-gated and proven.
Graphics PSO behavior is contract-gated and proven.
Compute PSO behavior is contract-gated and proven.
The synthetic shader corpus is contract-gated and proven.
Shader Model 6.5 is the reported compliant shader model.
Shader Model 6.6 is not reported yet.
WaveOps are not reported yet.
That last part matters. SM 6.6 and WaveOps should stay unreported until their dedicated probe corpus proves compile, link, reflection, binding, and runtime behavior. Passing one shader path is not enough to advertise a broader feature.
The comparator is the stable summary. For a clean pass, it should report that all required probes passed, no contract issues were found, and no unsupported feature is being over-advertised.
Full Strict Gate
Before merging meaningful D3D12, DXMT, or Metal changes, run the strict gate:
Some probes have warmup passes. During warmup, compiler_primary_cache_miss can appear while cache inputs are being dumped and converted. Treat it as a blocker only if it appears in the final required pass or if compare-contract.py reports that DXIL-to-MSL proof is false.
External Tooling
Optional external tooling can be bootstrapped with:
This prepares ignored local checkouts for tools such as DirectX-Headers, DirectXTK12, RenderDoc, GFXReconstruct, SPIRV-Cross, SDL_shadercross, and AMD Smoldr. These checkouts are not committed.
Game Capture And Offline Debugging
Game captures are diagnostic evidence, not the replacement for probe coverage.
For a game-safe preflight before launching a title:
The intended workflow is to capture once, then replay offline until the exact shader or PSO descriptor succeeds or reports a stable Metal error.
Developer Workflow
When changing D3D12, DXIL translation, Winemetal bridge code, DXGI, descriptors, PSOs, or feature reporting:
Make the implementation change.
Run the targeted probe lane for the behavior touched.
Update contracts if the support boundary changed.
Run validate-contracts.py.
Run the full probe matrix.
Run compare-contract.py.
Run validate-probe-matrix.py.
Only advertise a feature if the dedicated probe proves it.
If a game capture exposes a problem, turn that problem into a probe or contract entry. The long-term purpose of the SDK is to make game debugging repeatable without using the game itself as the only debugger.
Contribution Rule Of Thumb
A D3D12 support claim should be backed by at least one of:
A contract entry
A probe
A repeatable script
A baseline/result artifact
A documented unsupported or risky-stub ledger entry
If none of those exist yet, the change probably needs SDK coverage before it should be considered complete.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
D3D12 Metal SDK: Developer Guide
I added a repo-owned D3D12 Metal SDK under
tools/d3d12-metal-sdk/. This is now the main development and validation surface for MetalSharp's D3D12, DXMT, and Metal work.The goal is simple: D3D12 support should be evidence-driven. Before a feature is advertised, merged, or used as the basis for game debugging, it should be backed by a contract, a probe, a repeatable script, or an explicit unsupported/risky-stub ledger entry.
What The SDK Is
The SDK is a local validation harness for D3D12-on-Metal work through Wine-compatible DXMT runtimes.
It includes:
tools/d3d12-metal-sdk/contracts/tools/d3d12-metal-sdk/probes/tools/d3d12-metal-sdk/scripts/tools/d3d12-metal-sdk/results/tools/d3d12-metal-sdk/external/MetalSharp is one runtime profile, but the probes are intentionally normal Windows executables. They can run against the MetalSharp runtime, standalone Wine prefixes, DXMT development prefixes, and future host integrations.
Current Capability Truth
The current D3D12 posture is intentionally conservative:
That last part matters. SM 6.6 and WaveOps should stay unreported until their dedicated probe corpus proves compile, link, reflection, binding, and runtime behavior. Passing one shader path is not enough to advertise a broader feature.
Quick Start
From the repository root:
The comparator is the stable summary. For a clean pass, it should report that all required probes passed, no contract issues were found, and no unsupported feature is being over-advertised.
Full Strict Gate
Before merging meaningful D3D12, DXMT, or Metal changes, run the strict gate:
This is the merge authority for the SDK. Game launches and title captures are useful diagnostics, but they do not replace the strict gate.
Runtime Layout
For arbitrary Wine/DXMT testing, pass explicit runtime paths:
tools/d3d12-metal-sdk/scripts/run-probes.sh \ --wine /path/to/wine \ --prefix "$HOME/wine-d3d12-test" \ --dxmt-runtime /path/to/dxmt-runtimeThe runtime directory should contain:
Do not manually copy random
winemetal.dllorwinemetal.sobuilds into Wine/system directories. Use:Then validate:
The preflight checks D3D12, DXGI, and Winemetal exports, including the bridge exports needed by the rebuilt DXMT runtime.
Probe Groups
The default required probe matrix covers:
probe-loader: verifies the Wine process resolves the intended DXMT D3D12/DXGI route.probe-agility-ue5: validates app-local Agility SDK negotiation and modern device interface behavior.probe-device-caps: validates feature reporting, unsupported advanced features, and conservative capability denial.probe-dxgi-factory: validates factory, adapter, output, GPU-preference, and LUID behavior.probe-resources: validates committed resources, heaps, upload/readback, and basic resource behavior.probe-resource-views-formats: validates resource/view/format coverage.probe-queues: validates command queue and fence execution.probe-descriptors: validates descriptor heaps, root signatures, descriptor copies, static samplers, and null descriptors.probe-shaders: validates shader entry points, root signatures, argument binding, and the primary DXIL-to-MSL proof.probe-dxil-semantics: validates reduced SM6 opcode semantics with runtime readback.probe-shader-corpus: validates the permanent synthetic shader proof harness.probe-sm66-capabilities: audits SM 6.6 support and reporting denial/proof.probe-wave-ops: audits WaveOps support and reporting denial/proof.probe-reflection-abi: validates reflected shader bindings against the descriptor and root-signature ABI.probe-graphics-pso: validates graphics PSO matrix behavior and unsupported-stage rejection.probe-compute-pso: validates compute PSO matrix behavior.probe-command-replay: validates command-list, indirect, bundle, and replay behavior.probe-barriers-render-pass: validates barrier, render-pass, UAV, present, and readback visibility.probe-mini-suite: runs focused one-purpose D3D12 runtime mini-apps.Useful Probe Lanes
Fast focused mini-app suite:
DXIL semantic opcode groups:
Synthetic shader corpus:
SM 6.6 audit:
WaveOps audit:
Descriptor/root-signature ABI:
Graphics PSO matrix:
Compute PSO matrix:
Command replay:
Barriers/render-pass behavior:
Resource, view, and format coverage:
DXGI factory and swapchain/present:
Winemetal ABI/export gate:
Interpreting Results
Probe JSON is written under:
The important rule is: do not judge support from one probe in isolation. Run the comparator:
Some probes have warmup passes. During warmup,
compiler_primary_cache_misscan appear while cache inputs are being dumped and converted. Treat it as a blocker only if it appears in the final required pass or ifcompare-contract.pyreports that DXIL-to-MSL proof is false.External Tooling
Optional external tooling can be bootstrapped with:
This prepares ignored local checkouts for tools such as DirectX-Headers, DirectXTK12, RenderDoc, GFXReconstruct, SPIRV-Cross, SDL_shadercross, and AMD Smoldr. These checkouts are not committed.
Game Capture And Offline Debugging
Game captures are diagnostic evidence, not the replacement for probe coverage.
For a game-safe preflight before launching a title:
tools/d3d12-metal-sdk/scripts/preflight-before-game.sh \ --profile subnautica2 \ --game-dir "/path/to/game/Binaries/Win64"For offline shader replay against a known shader corpus:
python3 tools/d3d12-metal-sdk/scripts/replay-shader-corpus.py \ --profile subnautica2 \ --corpus "/path/to/shader-cache"For offline Metal PSO creation checks:
python3 tools/d3d12-metal-sdk/scripts/offline-pso-factory.py \ --profile subnautica2 \ --corpus "/path/to/shader-cache"If no shader corpus exists yet, use the bounded capture runner instead of a blind interactive launch:
The intended workflow is to capture once, then replay offline until the exact shader or PSO descriptor succeeds or reports a stable Metal error.
Developer Workflow
When changing D3D12, DXIL translation, Winemetal bridge code, DXGI, descriptors, PSOs, or feature reporting:
validate-contracts.py.compare-contract.py.validate-probe-matrix.py.If a game capture exposes a problem, turn that problem into a probe or contract entry. The long-term purpose of the SDK is to make game debugging repeatable without using the game itself as the only debugger.
Contribution Rule Of Thumb
A D3D12 support claim should be backed by at least one of:
If none of those exist yet, the change probably needs SDK coverage before it should be considered complete.
All reactions