wgpu-format-patching - SKILL.md Agent Skill

name: wgpu-format-patching description: When adding STORAGE_BINDING to compact texture formats in vendored wgpu-types, both |s_ro_wo| flags and |TextureUsages::STORAGE_BINDING| in allowed_usages are needed — the flags element must include s_ro_wo or the HAL receives zero storage access bits source: auto-skill extracted_at: '2026-06-15T03:49:26.570Z'

wgpu format table patching

When modifying vendored wgpu-types guaranteed_format_features() to add STORAGE_BINDING to compact formats, both elements of the returned tuple must be updated:

flags (first element) — must include s_ro_wo (= STORAGE_READ_ONLY | STORAGE_WRITE_ONLY). Without this, conv.rs:100-115 gates each HAL storage access bit on the corresponding flag, producing zero storage access bits despite allowed_usages passing validation.
allowed_usages (second element) — must include TextureUsages::STORAGE_BINDING.

Why the split exists: allowed_usages controls validation at texture-creation time. flags controls what the HAL actually enables. The pattern in every storage-capable format (Rgba8Unorm, Rgba16Float, etc.) uses both. They were decoupled in the BGRA8UNORM_STORAGE feature because write-only storage on BGRA8 is sometimes available when read-write is not.

Correct pattern per format:

// R8Unorm
Self::R8Unorm => (msaa_resolve | s_ro_wo, attachment | TextureUsages::STORAGE_BINDING),

// R16Float
Self::R16Float => (msaa_resolve | s_ro_wo, attachment | TextureUsages::STORAGE_BINDING),

// Rg16Float
Self::Rg16Float => (msaa_resolve | s_ro_wo, attachment | TextureUsages::STORAGE_BINDING),

// Rg11b10Ufloat (two branches — feature-gated)
let (rg11b10f_f, rg11b10f_u) =
    if device_features.contains(Features::RG11B10UFLOAT_RENDERABLE) {
        (msaa_resolve | s_ro_wo, attachment | TextureUsages::STORAGE_BINDING)
    } else {
        (msaa | s_ro_wo, basic | TextureUsages::STORAGE_BINDING)
    };

Vendoring approach: cargo vendor + [patch.crates-io] is sufficient — the native backends (Vulkan/DX12/Metal) query the driver for format capabilities directly; only guaranteed_format_features() in wgpu-types needs changes. The wgpu-hal backend tables do NOT need modification.

Verification: cargo check -p titan-rendering-3d — if the vendored crates compile, the format changes are syntactically correct. The runtime probe adapter.get_texture_format_features(R16Float).allowed_usages.contains(STORAGE_BINDING) confirms the formats are exposed at device creation time.