renderer-shader-host-layout-sync

name	renderer-shader-host-layout-sync
description	Keep host C/C++ structs and the shaders that read them byte-for-byte in sync — SSBO/UBO/push-constant layout, binding indices, and shared constants across GLSL/MSL/SPIR-V. Use when Codex adds or changes a struct shared between host code and a shader, wires descriptor/binding layouts, shares a push-constant block across pipelines, or debugs "wrong pixels with no crash" layout-drift bugs.

Renderer Shader/Host Layout Sync

Purpose

A renderer is two programs — host code and shader code — reading the same bytes through two compilers that pad, align, and lay out independently. When their view of a struct, a binding index, or a constant drifts, the symptom is the worst kind of bug: no crash, just wrong pixels, because array[i] reads from the wrong offset for every i >= 1. It reads like a material or shading bug; it is a layout bug. This skill makes the host↔shader contract enforced at build time instead of discovered in an image. It is the GPU-side companion to contract-first-ffi (which owns the host↔language-binding boundary) and renderer-backend-port (cross-language alignment differences).

Pin the layout at the host translation unit, not in your head

• Any struct shared host↔shader must be byte-identical. The shading language applies its own alignment (a member needing 16-byte alignment grows the whole struct), so a struct that "looks identical" can mismatch. Bake the expected sizeof as a named constant and static_assert it — plus offsetof for every load-bearing field — in the backend translation unit, so adding or reordering a field fails the build, not the GPU. (Canonical war story: a host material struct at 192 bytes vs a shader struct at 112 rendered instanced geometry with the wrong material — silent until the size assert was added.)
• Treat the assert as the authority; do not transcribe the numbers anywhere else. The point is that one place fails loudly when the layout moves.

Changing a shared struct is a checklist, not an edit

• Bumping a shared struct requires, together: update the host struct, update the shader's mirror struct, update the size/offset asserts, and clear the persisted pipeline / SPIR-V cache — a stale cache loaded against new shader bytecode produces wrong or crashing pipelines. A "how to change this safely" comment at the struct should name every step.

One file owns the binding layout; everything mirrors it

• With many SSBO/UBO/AS bindings shared across raygen/hit/miss/compute shaders, pick one file as the authoritative source of binding numbers and have the host build its descriptor-set layout at the same indices. A second pass (deferred shading, a debug view) must mirror the producer's bindings exactly, or it binds — and reads — the wrong buffer. The same rule covers shared constants (a K-buffer depth, a workgroup size): one definition, mirrored with a guard comment, never two literals. A compute shader's local_size_x and the host's ceil(count / local_x) dispatch divisor are the same number in two places — drive both from one build-time define.

A shared push-constant block has fixed offsets — declare the whole block

• Reusing one push-constant struct across pipelines (single-camera, tiled, curve) lets shared closest-hit/miss code read common fields (a ground plane, a scene scale) at the same byte offsets regardless of which raygen ran. Each consuming shader must declare the full block even if it uses two fields, or the offsets shift; pad explicitly to the alignment the shared fields need.
• (Surprising, and worth a comment where it lives:) flags are sometimes smuggled into the unused float slots of a shared matrix push-constant and read back via floatBitsToUint(). The trap is the storage convention — a GLSL mat4 is column-major, so the host's row-major struct order maps to specific [col][row] indices; get the mapping wrong and you read a different flag.

Know your block-layout rule and don't change it silently

• std430 vs scalar block layout (GL_EXT_scalar_block_layout) changes how a vec3 packs with a following scalar; the renderer's structs may rely on scalar packing to stay 16-byte aligned without explicit padding. Switching the layout qualifier silently reinterprets every buffer — it is part of the contract, not a free toggle.
• Bind by reflected size: when a backend binds a uniform/argument struct by reflection or a fixed byte length, the shading-language padding makes the required buffer larger than the live fields; allocate and send the full reflected size (e.g. pad a 20-byte payload to 48 because a uint3/float4x4 member forces 16-byte alignment) or the bind is rejected or undersized.

Validate the layout, not just the image

• A reduced fixture that reads element [1] (not just [0]) of every shared array exposes stride/offset drift that a single-element scene hides. Capture the relevant term AOV (material ID, base color) and confirm element N matches authored data before trusting beauty. Keep the size/offset asserts in every build configuration.

Anti-Patterns

• A shared struct with no compile-time size/offset assert ("it looks the same").
• Bumping a shared struct without clearing the pipeline/SPIR-V cache.
• Binding indices or shared constants duplicated as literals in two files.
• A shader that declares only the push-constant fields it uses (offset shift).
• Flipping std430↔scalar, or sending only the live-field size of a reflected struct.
• Diagnosing a stride/offset bug as a material or shader-math bug.

Handoff

Report which structs/bindings/constants are shared host↔shader, where each is asserted, the block-layout rule in force (std430/scalar), the pipeline-cache-clear step if a struct changed, and the element-[1] AOV evidence that the layout is correct. Cross-reference renderer-backend-port for cross-language alignment and contract-first-ffi for the host↔binding boundary.