Skip to content

Texture bindings: The texture kind warning names the size, mip levels and format of the texture that was bound - #210

Merged
jdrly merged 1 commit into
mainfrom
diag/texture-kind-warning-names-texture
Nov 16, 2026
Merged

jdrly merged 1 commit into
mainfrom
diag/texture-kind-warning-names-texture

Conversation

@jdrly

@jdrly jdrly commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

What changes

A player's log had ten texture kind mismatch lines, and none of them said which texture was bound. #151 binds the null texture of the declared kind in that case, which reads (0, 0, 0, 0) as native D3D9 does on Nvidia and as DXVK does. That's right as long as the bound texture is a black placeholder. Some Windows drivers (AMD, Intel, WARP, per Wine's test_mismatched_sample_types) sample the bound texture instead, so with a real texture there d9mt would draw differently from them, and the log couldn't tell us. We don't go back to players for a second log, so the first one has to say it.

The line now describes the bound texture:

D9MT: texture kind mismatch: ps <hash> sampler s5 declares cube, a 2D texture (16x16, 1 level, BC1_RGBA) is bound: bound as the null cube texture instead

That's width x height (x depth for a 3D image), the mip level count and the Metal pixel format name from the image's creation info. The back end doesn't keep the D3D9 format, so D3DFMT_DXT1 prints as BC1_RGBA, DXT2/3 as BC2_RGBA, DXT4/5 as BC3_RGBA. rstore::formatName (the RESTORE lines' table) now names every MtlFormat pixel format for this. Before, it named only render-target formats and printed the rest as fmt<n>.

One line per what. The key is now shader, stage, sampler, bound kind and the texture's description (format, width, height, depth, mips). I chose that over keeping the first texture only. A game that binds a placeholder first and a real texture later at the same sampler is exactly the case the line exists to show. A recreated placeholder with the same description still logs once. The cap stays at 16 lines and the (further mismatches not logged) note stays. The cost is that one shader binding many differently-sized textures at a mismatched sampler fills the cap sooner.

While there: mtl_texture_kind.h said a mismatched texture "reads zero, as an unbound sampler does". The alpha differs: (0, 0, 0, 0) mismatched, (0, 0, 0, 1) unbound, where the shader's null check returns before any texture read. The comment now says so.

No issue: this comes from a player's bug report.

  • ADR: none (ADR-0007 for the evidence below)

How to verify

  • Checks builds both drivers and runs the native tests and test-null-kind.sh. None of them checks this line's text, see Evidence.
  • On a Mac, test/code_cube_kind.c binds a 2D texture at a dcl_cube sampler. Its wine.log should show the new line with the test's texture size and format, and the frames should match base.

Evidence

Proof. Head 6b4cc91 on main 002b1c6. Nothing of d9mt builds on the machine I worked on, so the hosted Checks run on this head is the build and test gate.

  • Hosted Checks: green on 6b4cc91 (run 43773564555). Both drivers built with no warning from the changed files. stats_test, texture_kind_test and scripts/test-null-kind.sh passed. AIR codegen id 25fc2491f11d0902328bd623fa12d2d73b7eeebb877e6dfd30d85b78c8e7a6c2, main's. The non-blocking test-perf-abba.sh step fails the same way on main's last run (43708116331), so this PR didn't cause it.

  • Texture bindings: A texture of another kind than the sampler declares binds as the null texture of the declared kind #151's guard is unchanged. Both call sites still write the null texture of the declared kind: nullOf(e.dim, …) stays in the argument-buffer word, and appendTableTexture(…, nullTextureId(…)) stays in the argument table. The bound view goes to the warning only as a const reference. The function reads its image's CPU-side creation info (MtlImageInfo) and nothing else, so the view is never read on the GPU and never bound.

  • Hot path. The new work is inside noteTextureKindMismatch, which is still noinline, cold and is called only after texkind::matches has failed. On the match path the call sites are the same. In the mismatch branch, the call passes *tv instead of tv->kind. GPU gates: A bench set that reports counters, bench timings and hot-path code of base against head #207's hot-code comparison may report the functions holding those call sites as changed by an instruction or so.

  • AIR codegen id. No codegen input changes. The id is the digest of the objects in scripts/build-bridge.sh's CODEGEN_OBJS (airlib, air_cache.c, cache.c, dxbc-spirv ir/util, the AIR builder, LLVM). This PR touches only driver/backend/ and driver/mtl/, which go into d3d9.dll, not the bridge. Checks printed 25fc2491f11d…, main's.

  • Format table. I checked the 56 names in formatName against enum class MtlFormat in driver/mtl/mtl_types.h with a script: every pixel format is named, every value matches its enumerator's name, and nothing else is in the table. The two vertex-attribute markers (900, 901) stay fmt<n>. stats_test's fmt123456 check still holds.

  • Tests. No test checks this warning's text: texture_kind_test.cpp covers the kind logic, code_cube_kind.c the pixels. As the brief says, I didn't build a seam for it.

  • App. I searched jdrly/swtor-on-mac for this line's text (texture kind mismatch, is bound, null cube): nothing matches. session-report.sh picks specific D9MT: lines and not this one. RESTORE descriptions with named formats instead of fmt<n> are treated as plain text there.

Performance (PERFORMANCE.md §1). Kind: diagnostic. Default path: nothing changes until a mismatch happens. Enabled cost: on a mismatch, the existing call now copies a small struct and compares up to 16 entries under the existing mutex, and formats one string per new line (at most 16 per session). Timing pending. No guard is calibrated, and none was run.

Still needs a Mac (no window granted for this lane), for the DX9 dispatcher to batch:

  • the hash suite against base, with MTL_DEBUG_LAYER=1, D9MT_NO_ATTACHMENT_OPT=1 and d3d9.reproducibleCommandStream=True (it should be identical: no rendering change);
  • code_cube_kind once, to read the new line in its log;
  • the release-toolchain AIR codegen id (25fc2491…).

Definition of Done

  • scripts/build-bridge.sh and scripts/build-driver.sh for ARCH=x64 and ARCH=x86 build clean: hosted Checks on the head.
  • Hash suite frame-identical to base: needs a Mac (above).
  • Bug fix regression test: not a bug fix. It's a diagnostic. No existing seam checks the line (above).
  • Native tests: hosted Checks.
  • Performance evidence: diagnostic, cold path only, timing pending (above).
  • AIR codegen id: main's, 25fc2491… (hosted Checks). The release-toolchain id still needs a Mac.
  • No new environment variable or dxvk.conf option.
  • Terms follow CONTEXT.md. No decision changed.
  • Independent agent review: APPROVE at 6b4cc91 (below).
  • UAT: needs a Mac. code_cube_kind shows the new line.

Review

Codex (gpt-6.1-sol, reasoning high), one round at 6b4cc91: no findings in standards, spec or bugs. It agreed with keying on the description, accepting that the cap fills sooner, and with not building a test seam. It checked that both call sites keep the null binding and that the new code compiles as C++17 by reading it. It didn't build anything. Verdict: APPROVE.

Risks and what I didn't do

  • Risk. A log-only change. If the new code were wrong, the most a player could see is a garbled or missing warning line. The pixels and the binding are as on main. Whoever reads the next bug report would notice.
  • The format is Metal's, not D3D9's. DXT2 and DXT3 (and DXT4 and DXT5) print the same name. Keeping the D3D9 format would mean adding it to the image's creation info for this one line, and I didn't.
  • How to revert. Revert the squash commit.

… and format of the texture that was bound

A player's log had ten "texture kind mismatch" lines and could not show which
texture was bound at those samplers. Research found that SWTOR binds its 16x16
flat black DXT1 placeholder there in a captured session, so the null-cube
fallback draws the same pixels as Windows; whether the player's session bound
the same texture could only be inferred, and a real texture at such a sampler
would draw differently on some Windows drivers.

The warning now describes the bound texture from its image's creation info:
width x height (x depth for a 3D image), the mip level count and the Metal
pixel format name (the D3D9 format isn't kept in the back end; DXT1 prints as
BC1_RGBA), for example "a 2D texture (16x16, 1 level, BC1_RGBA) is bound".
rstore::formatName names every MtlFormat pixel format for that.

A texture with another description at the same shader, sampler and bound kind
gets its own line, so a real texture bound after the placeholder shows up; the
cap of 16 lines stays. The description is read only inside the cold function,
after the mismatch is known; the view is never read on the GPU or bound, so
#151's guard is unchanged. No AIR codegen input changes.

The comment in mtl_texture_kind.h said a mismatched texture reads zero "as an
unbound sampler does": the alpha differs ((0,0,0,0) mismatched, (0,0,0,1)
unbound, as native D3D9 on Nvidia and DXVK). Corrected.
@jdrly jdrly added area:backend The seam and the Metal 4 backend, submission, presentation (driver/mtl, driver/backend) DX9 The Direct3D 9 build (d9mt) labels Nov 15, 2026
@jdrly jdrly self-assigned this Nov 15, 2026
@jdrly
jdrly merged commit e9c6cf9 into main Nov 16, 2026
5 checks passed
@jdrly

jdrly commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

GPU gate on an M1 (macOS 27): hash suite, default and debug against main 002b1c6, pass. 58 programs; only code_mtlock's frames differ, as always; validation, invalid usage and lifetime 0 on both sides. The hash run doesn't keep logs of passing programs, so the new line itself wasn't read there; it shows up the next time a log hits the mismatch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:backend The seam and the Metal 4 backend, submission, presentation (driver/mtl, driver/backend) DX9 The Direct3D 9 build (d9mt)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant