Skip to content

Commit dcdb295

Browse files
proggeramlugproggeramlug
committed
Document Khronos material qualification
1 parent b40d28b commit dcdb295

2 files changed

Lines changed: 233 additions & 0 deletions

File tree

‎docs/evidence/issue-133-khronos-materials-v1.json‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
{
2+
"schema": "bloom-khronos-material-qualification-evidence-v1",
3+
"issue": 133,
4+
"qualified_revision": "b40d28b3f52332fc210f1382fa9cb4efa5450f8f",
5+
"commits": {
6+
"pinned_qualification": "d2032b0",
7+
"static_node_volume_scale": "b40d28b"
8+
},
9+
"adapter": {
10+
"backend": "Metal",
11+
"profile": "native-full",
12+
"selected_tier": "high-end",
13+
"ray_query": true
14+
},
15+
"corpus": {
16+
"repository": "https://github.com/KhronosGroup/glTF-Sample-Assets",
17+
"revision": "2bac6f8c57bf471df0d2a1e8a8ec023c7801dddf",
18+
"assets": {
19+
"alpha-blend-mode": {
20+
"name": "AlphaBlendModeTest",
21+
"license": "CC-BY-4.0",
22+
"sha256": "37c3577d143071b42dd46e9d942b157837eb25c6340112171d7faecaa987b14e"
23+
},
24+
"transmission": {
25+
"name": "TransmissionTest",
26+
"license": "CC0-1.0",
27+
"sha256": "dd9732dae5517f8605ad4324d78b077b969c3e8357c056280d0a4e4b67797d15"
28+
},
29+
"attenuation": {
30+
"name": "AttenuationTest",
31+
"license": "CC-BY-4.0",
32+
"sha256": "7ca161b7f8a9e4b2ac1f7f75816b5848bb31f3b4c226c4cb731b487c8809b756"
33+
},
34+
"transmission-order": {
35+
"name": "TransmissionOrderTest",
36+
"license": "CC0-1.0",
37+
"sha256": "d904b6cd6c83792fd4a4d9ad4f0366bde76a63e347541c465f2ad4c5baf22a21"
38+
}
39+
}
40+
},
41+
"isolated_static_node_scale_correction": {
42+
"control_revision": "d2032b0",
43+
"control_attenuation_sha256": "8643da1ff400f0d3a5829df11798afb925243ff9c7cf6da4039504986b62ab1e",
44+
"corrected_attenuation_sha256": "a2a1b2c3c5a4969e708f09566dbc476a602e007a996152bcd2f857c55c46df50",
45+
"control_node_scale_chroma_ramp": [36, 39, 36, 37, 39],
46+
"corrected_node_scale_chroma_ramp": [18, 29, 36, 41, 42],
47+
"control_semantic_gate": "fail",
48+
"corrected_semantic_gate": "pass",
49+
"diff": {
50+
"width": 1920,
51+
"height": 1440,
52+
"rmse_luminance": 0.004399808,
53+
"ssim_luminance": 0.998071194,
54+
"percent_above_0_02": 2.013852835,
55+
"mean_oklab_delta": 0.000606760,
56+
"mean_edge_delta": 0.000184952,
57+
"changed_region": "five AttenuationTest Node Scale row cubes"
58+
},
59+
"unchanged_control_sha256": {
60+
"alpha-blend-mode": "6fc0ca56217f87f1edf6e9ff99403b417fe8b0bad3a84747eb9837bbc8e92043",
61+
"transmission": "46f840a1700483cfad8b4ab5a674e5f2e6772eca637e891bc5aac03233bee1c0",
62+
"transmission-order": "bc92a884c41b4e349642222620776855190850f1a34373975dcd490ee5e1525b"
63+
}
64+
},
65+
"final_run": {
66+
"automation_status": "pass",
67+
"review_state": "candidate-human-review-required",
68+
"runs_per_case": 2,
69+
"all_byte_exact": true,
70+
"supported_field_diagnostics": 0,
71+
"cases": {
72+
"alpha-blend-mode": {
73+
"capture_sha256": "6fc0ca56217f87f1edf6e9ff99403b417fe8b0bad3a84747eb9837bbc8e92043",
74+
"semantic_gate": "green-checks",
75+
"status": "pass"
76+
},
77+
"transmission": {
78+
"capture_sha256": "46f840a1700483cfad8b4ab5a674e5f2e6772eca637e891bc5aac03233bee1c0",
79+
"semantic_gate": "material-variation",
80+
"status": "pass"
81+
},
82+
"attenuation": {
83+
"capture_sha256": "a2a1b2c3c5a4969e708f09566dbc476a602e007a996152bcd2f857c55c46df50",
84+
"semantic_gate": "attenuation-node-scale-ramp",
85+
"node_scale_chroma_ramp": [18, 29, 36, 41, 42],
86+
"status": "pass"
87+
},
88+
"transmission-order": {
89+
"capture_sha256": "bc92a884c41b4e349642222620776855190850f1a34373975dcd490ee5e1525b",
90+
"semantic_gate": "material-variation",
91+
"status": "pass"
92+
}
93+
}
94+
},
95+
"runtime_contract": {
96+
"transmission_uniform_bytes_before": 96,
97+
"transmission_uniform_bytes_after": 96,
98+
"added_render_passes": 0,
99+
"added_draws": 0,
100+
"added_gpu_allocations": 0,
101+
"added_texture_samples": 0,
102+
"added_bindings": 0,
103+
"added_shader_branches": 0,
104+
"cpu_material_scalars_per_mesh": 1,
105+
"joint_weight_accessor_collection": "moved outside vertex loop"
106+
},
107+
"qualification": {
108+
"shared_tests_runnable_passed": 329,
109+
"shared_tests_ignored": 1,
110+
"gpu_goldens_passed": 59,
111+
"gpu_goldens_ignored": 2,
112+
"render_target_tests_passed": 4,
113+
"native_models3d_check": "pass",
114+
"wasm32_web_check": "pass",
115+
"ffi_schema_parity": "pass",
116+
"format": "pass",
117+
"file_size_ratchet": "pass",
118+
"quality_governance_tests_passed": 17,
119+
"visual_diff_fault_tests_passed": 3,
120+
"cooker_tests_passed": 17,
121+
"khronos_cases_passed": 4
122+
},
123+
"remaining": [
124+
"explicit human reference-image approval",
125+
"approved baseline installation remains intentionally separate"
126+
]
127+
}

‎docs/evidence/issue-133-khronos-materials-v1.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Issue #133 Khronos material qualification v1
2+
3+
This checkpoint qualifies Bloom's alpha, transmission, volume attenuation,
4+
and transmission-order rendering against four official Khronos
5+
`glTF-Sample-Assets` controls. The final hardware run passed at revision
6+
`b40d28b3f52332fc210f1382fa9cb4efa5450f8f` on the native high-end Metal
7+
profile with hardware ray queries.
8+
9+
## Pinned corpus
10+
11+
The opt-in `tools/quality/khronos_materials.py` runner downloads assets only
12+
from Khronos revision
13+
`2bac6f8c57bf471df0d2a1e8a8ec023c7801dddf`, verifies every GLB hash, and
14+
records the source metadata and license:
15+
16+
| Control | License | GLB SHA-256 |
17+
|---|---|---|
18+
| AlphaBlendModeTest | CC-BY-4.0 | `37c3577d143071b42dd46e9d942b157837eb25c6340112171d7faecaa987b14e` |
19+
| TransmissionTest | CC0-1.0 | `dd9732dae5517f8605ad4324d78b077b969c3e8357c056280d0a4e4b67797d15` |
20+
| AttenuationTest | CC-BY-4.0 | `7ca161b7f8a9e4b2ac1f7f75816b5848bb31f3b4c226c4cb731b487c8809b756` |
21+
| TransmissionOrderTest | CC0-1.0 | `d904b6cd6c83792fd4a4d9ad4f0366bde76a63e347541c465f2ad4c5baf22a21` |
22+
23+
The source repository is
24+
[KhronosGroup/glTF-Sample-Assets](https://github.com/KhronosGroup/glTF-Sample-Assets).
25+
The run is reproducible with:
26+
27+
```sh
28+
python3 tools/quality/khronos_materials.py \
29+
--out tools/quality/out/khronos-materials
30+
```
31+
32+
## Static-node volume correction
33+
34+
The first qualification run exposed a real physical-material defect. Bloom
35+
baked static glTF node transforms into vertex positions but discarded their
36+
scale before evaluating `KHR_materials_volume`. The official AttenuationTest
37+
requires its Node Scale row to deepen absorption as scale increases from 0.25
38+
to 2.0.
39+
40+
At clean pre-fix revision `d2032b0`, median front-face blue-minus-red values
41+
were `[36, 39, 36, 37, 39]`; the scale response was effectively flat. The
42+
corrected import retains the mean baked basis scale separately from the
43+
authored `thicknessFactor`. It is consumed consistently by camera refraction,
44+
transmitted shadows, and transparent GI, while later draw/instance scale
45+
continues to be applied normally.
46+
47+
The corrected ramp is `[18, 29, 36, 41, 42]`. A dependency-free automated
48+
gate now checks that this row has a materially increasing absorption span.
49+
Running the new gate against the clean pre-fix binary fails only
50+
AttenuationTest, proving that it detects the defect it was added to prevent.
51+
52+
An isolated pre/fix image comparison changed only the five Node Scale cubes:
53+
54+
- pre-fix attenuation SHA-256:
55+
`8643da1ff400f0d3a5829df11798afb925243ff9c7cf6da4039504986b62ab1e`;
56+
- corrected attenuation SHA-256:
57+
`a2a1b2c3c5a4969e708f09566dbc476a602e007a996152bcd2f857c55c46df50`;
58+
- luminance RMSE: `0.004399808`;
59+
- luminance SSIM: `0.998071194`;
60+
- pixels above a 0.02 tolerance: `2.013852835%`;
61+
- mean OKLab delta: `0.000606760`;
62+
- mean edge delta: `0.000184952`.
63+
64+
The other official controls are byte-exact before and after the correction:
65+
66+
| Control | Capture SHA-256 |
67+
|---|---|
68+
| AlphaBlendModeTest | `6fc0ca56217f87f1edf6e9ff99403b417fe8b0bad3a84747eb9837bbc8e92043` |
69+
| TransmissionTest | `46f840a1700483cfad8b4ab5a674e5f2e6772eca637e891bc5aac03233bee1c0` |
70+
| TransmissionOrderTest | `bc92a884c41b4e349642222620776855190850f1a34373975dcd490ee5e1525b` |
71+
72+
## Final qualification
73+
74+
Every final control rendered twice with identical SHA-256 values, passed its
75+
semantic image gate, produced non-flat/non-black output, and emitted no
76+
supported-field import or validation diagnostics. The qualification tool
77+
records these as review candidates and never installs or approves a baseline;
78+
reference-image approval remains an explicit human action.
79+
80+
The implementation preserves the 96-byte transmission GPU uniform and adds no
81+
render pass, draw, GPU allocation, texture sample, binding, or shader branch.
82+
It adds one CPU material scalar and one bounded scale multiplication when
83+
material uniforms are prepared. The textured loader also moves joint and
84+
weight accessor collection out of the vertex loop, removing repeated
85+
whole-accessor decoding.
86+
87+
Staged and CPU-only loaders now share the same static node-transform,
88+
instancing, normal/tangent, bounds, and volume-thickness contract as the
89+
textured loader. This fixes previously missing scene transforms and instances
90+
in those paths; it does not add work to the existing textured render path.
91+
92+
## Regression gates
93+
94+
- 330 shared tests passed in the complete suite (329 runnable, 1 ignored);
95+
- 59 GPU goldens passed, with 2 hardware-policy cases intentionally ignored;
96+
- all 4 render-target tests passed;
97+
- native release `models3d` and `wasm32-unknown-unknown` Web builds passed;
98+
- FFI/schema parity passed for macOS, Linux, Windows, Android, Apple targets,
99+
and Web;
100+
- formatting and the file-size ratchet passed;
101+
- 17 quality-governance tests, 3 visual-diff fault tests, and 17 cooker tests
102+
passed;
103+
- all four final Khronos cases passed twice at the qualified revision.
104+
105+
Machine-readable measurements accompany this note in
106+
`docs/evidence/issue-133-khronos-materials-v1.json`.

0 commit comments

Comments
 (0)