refactor(material): split shader programs from material instances #941

Merged
SakulFlee merged 3 commits from feat/renderer-material-v2 into main 2026-10-26 17:13:26 +00:00
Collaborator

Summary

Phase 3: split compiled shader programs from material instances, add a shared pass-aware pipeline cache, and introduce material render state.

Programs, materials and pipelines

  • New ShaderProgram: assembled shader module, pipeline layout, material bind-group layout and static pipeline state. It does not own textures, buffers or a render pipeline.
  • New PipelineCache: keyed by program id + pass + color format + depth format. Programs are tracked weakly, so pipelines for dropped materials are pruned instead of leaking.
  • MaterialShader owns a ShaderProgram, its material bind group/variables and a cached forward pipeline.
  • ShaderDescriptor now separates layout construction from variable realization:
    • bind_group_layout_entries / bind_group_layout_only
    • realize_variables
    • bind_group_with_layout
    • Existing bind_group_layout / bind_group keep their behavior.
  • Add TextureDescriptor::view_dimension() so layouts can be created before texture data exists.
  • Add PipelineCacheResource and share one cache per device.
  • Fix the material cache path: it used or_insert(value), which eagerly constructed a new material and pipeline even on a hit. Cache hits now only clone the existing entry.

Material render state

MaterialShaderDescriptor now carries:

  • AlphaMode::{Opaque, Mask(cutoff), Blend}
  • BlendState
  • depth_write / depth_compare
  • RenderQueue::{Opaque, Transparent}
  • cast_shadows / receive_shadows

ShaderProgram builds the forward pipeline from this state, and MaterialShader exposes it for renderer queue selection. Defaults keep every existing material opaque, replace-blended, depth-writing and shadow-casting.

PassKind currently exposes Forward; shadow/G-buffer variants and the Surface contract are the next phase-3 changes. No visual change in this PR.

Lockfile

The v1.6.0 version bump left workspace package versions at 1.5.0 in Cargo.lock; refreshed in a separate commit.

Verification

  • cargo fmt --all -- --check
  • cargo clippy -p orbital_texture -p orbital_shader_core -p orbital_material_shader -p orbital_model -p orbital_renderer -p orbital_app -- -D warnings
  • cargo test -p orbital_texture -p orbital_shader_core -p orbital_material_shader -p orbital_model -p orbital_renderer -p orbital_app --no-fail-fast
  • GUI examples were not launched in this environment (no display/GPU).

Refs #781.

## Summary Phase 3: split compiled shader programs from material instances, add a shared pass-aware pipeline cache, and introduce material render state. ### Programs, materials and pipelines - New `ShaderProgram`: assembled shader module, pipeline layout, material bind-group layout and static pipeline state. It does not own textures, buffers or a render pipeline. - New `PipelineCache`: keyed by program id + pass + color format + depth format. Programs are tracked weakly, so pipelines for dropped materials are pruned instead of leaking. - `MaterialShader` owns a `ShaderProgram`, its material bind group/variables and a cached forward pipeline. - `ShaderDescriptor` now separates layout construction from variable realization: - `bind_group_layout_entries` / `bind_group_layout_only` - `realize_variables` - `bind_group_with_layout` - Existing `bind_group_layout` / `bind_group` keep their behavior. - Add `TextureDescriptor::view_dimension()` so layouts can be created before texture data exists. - Add `PipelineCacheResource` and share one cache per device. - Fix the material cache path: it used `or_insert(value)`, which eagerly constructed a new material and pipeline even on a hit. Cache hits now only clone the existing entry. ### Material render state `MaterialShaderDescriptor` now carries: - `AlphaMode::{Opaque, Mask(cutoff), Blend}` - `BlendState` - `depth_write` / `depth_compare` - `RenderQueue::{Opaque, Transparent}` - `cast_shadows` / `receive_shadows` `ShaderProgram` builds the forward pipeline from this state, and `MaterialShader` exposes it for renderer queue selection. Defaults keep every existing material opaque, replace-blended, depth-writing and shadow-casting. `PassKind` currently exposes `Forward`; shadow/G-buffer variants and the `Surface` contract are the next phase-3 changes. No visual change in this PR. ### Lockfile The v1.6.0 version bump left workspace package versions at 1.5.0 in `Cargo.lock`; refreshed in a separate commit. ## Verification - `cargo fmt --all -- --check` - `cargo clippy -p orbital_texture -p orbital_shader_core -p orbital_material_shader -p orbital_model -p orbital_renderer -p orbital_app -- -D warnings` - `cargo test -p orbital_texture -p orbital_shader_core -p orbital_material_shader -p orbital_model -p orbital_renderer -p orbital_app --no-fail-fast` - GUI examples were not launched in this environment (no display/GPU). Refs #781.
The v1.6.0 version bump left workspace package versions at 1.5.0 in Cargo.lock. Regenerate it so the lockfile matches the workspace manifests.
refactor(material): split shader programs from material instances
Some checks failed
Lint / lint (pull_request) Successful in 7m2s
PR / test (pull_request) Has been cancelled
Templates / templates (pull_request) Has been cancelled
aedc3335cf
Add ShaderProgram (assembled module, pipeline layout, material layout) and a pass-aware PipelineCache keyed by program/pass/color/depth. MaterialShader now owns a program, its material bind group/variables and a cached forward pipeline.

Refactor ShaderDescriptor to build bind-group layouts and realize variables separately, so a program can own its layout before texture data exists. Add TextureDescriptor::view_dimension for layout-only creation.

Share a device-wide PipelineCache through ECS and fix the material cache path so cache hits no longer eagerly construct a new material and pipeline.
feat(material): add material render state and alpha modes
All checks were successful
Lint / lint (pull_request) Successful in 2m55s
Templates / templates (pull_request) Successful in 15m35s
PR / test (pull_request) Successful in 20m48s
b84150505c
Material descriptors now carry alpha mode, blend state, depth write/compare, render queue, and shadow flags. ShaderProgram builds the forward pipeline from that state, and MaterialShader exposes it for queue selection and sorting in the renderer.

Defaults remain opaque, replace-blended, depth-writing, less-tested and shadow-casting, so existing materials are unchanged.

Smart test results

Result: PASS

Scope: full workspace

Reason: workspace-level change: Cargo.lock

Elapsed: 14m 6s

Workflow run

Overall: 439 tests, 429 passed, 0 failed, 10 skipped

Nextest: 428 tests, 428 passed, 0 failed, 0 skipped
Doctests: 11 tests, 1 passed, 0 failed, 10 skipped

Outcome charts are split between nextest and doctests. The timing chart covers nextest only.

Crate Nextest Passed Failed Skipped Doctests Time
orbital 1 1 0 0 - 7.24s
orbital_2d 29 29 0 0 0/1 0.24s
orbital_app 10 10 0 0 0/1 0.08s
orbital_camera 4 4 0 0 - 0.04s
orbital_core 2 2 0 0 - 0.02s
orbital_debug_render 0 0 0 0 0/1 0.00s
orbital_debug_ui 45 45 0 0 0/1 0.36s
orbital_ecs 114 114 0 0 0/2 0.91s
orbital_ecs_bridge 39 39 0 0 - 0.33s
orbital_file_manager 5 5 0 0 - 0.11s
orbital_iced 25 25 0 0 - 0.22s
orbital_importer_gltf 13 13 0 0 - 0.23s
orbital_input 11 11 0 0 - 0.09s
orbital_light 6 6 0 0 - 0.05s
orbital_macros 0 0 0 0 0/1 0.00s
orbital_material_shader 2 2 0 0 - 0.01s
orbital_math 4 4 0 0 - 0.03s
orbital_procgeo 2 2 0 0 - 0.02s
orbital_render_graph 6 6 0 0 - 0.05s
orbital_renderer 4 4 0 0 - 0.03s
orbital_resources 20 20 0 0 - 2.92s
orbital_shader_core 0 0 0 0 1/1 0.00s
orbital_shader_preprocessor 12 12 0 0 - 0.10s
orbital_shadow 3 3 0 0 - 0.02s
orbital_text 14 14 0 0 0/1 0.56s
orbital_texture 11 11 0 0 - 0.10s
orbital_touch_ui 1 1 0 0 0/1 0.01s
orbital_ui 32 32 0 0 0/1 0.24s
orbital_world_environment 13 13 0 0 - 0.11s
pie showData
    title Nextest outcomes
    "Passed" : 428
pie showData
    title Doctest outcomes
    "Passed" : 1
    "Skipped" : 10
xychart-beta
    title "Slowest crates (nextest seconds)"
    x-axis ["orbital", "orbital_resources", "orbital_ecs", "orbital_text", "orbital_debug_ui", "orbital_ecs_bridge", "orbital_2d", "orbital_ui"]
    y-axis "Seconds" 0 --> 7.3
    bar [7.24, 2.92, 0.91, 0.56, 0.36, 0.33, 0.24, 0.24]
<!-- orbital-ci-test-results --> ## Smart test results **Result:** PASS **Scope:** full workspace **Reason:** workspace-level change: Cargo.lock **Elapsed:** 14m 6s [Workflow run](https://forgejo.sakul-flee.de/SakulFlee/Orbital/actions/runs/661) **Overall:** 439 tests, 429 passed, 0 failed, 10 skipped **Nextest:** 428 tests, 428 passed, 0 failed, 0 skipped **Doctests:** 11 tests, 1 passed, 0 failed, 10 skipped _Outcome charts are split between nextest and doctests. The timing chart covers nextest only._ | Crate | Nextest | Passed | Failed | Skipped | Doctests | Time | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | orbital | 1 | 1 | 0 | 0 | - | 7.24s | | orbital_2d | 29 | 29 | 0 | 0 | 0/1 | 0.24s | | orbital_app | 10 | 10 | 0 | 0 | 0/1 | 0.08s | | orbital_camera | 4 | 4 | 0 | 0 | - | 0.04s | | orbital_core | 2 | 2 | 0 | 0 | - | 0.02s | | orbital_debug_render | 0 | 0 | 0 | 0 | 0/1 | 0.00s | | orbital_debug_ui | 45 | 45 | 0 | 0 | 0/1 | 0.36s | | orbital_ecs | 114 | 114 | 0 | 0 | 0/2 | 0.91s | | orbital_ecs_bridge | 39 | 39 | 0 | 0 | - | 0.33s | | orbital_file_manager | 5 | 5 | 0 | 0 | - | 0.11s | | orbital_iced | 25 | 25 | 0 | 0 | - | 0.22s | | orbital_importer_gltf | 13 | 13 | 0 | 0 | - | 0.23s | | orbital_input | 11 | 11 | 0 | 0 | - | 0.09s | | orbital_light | 6 | 6 | 0 | 0 | - | 0.05s | | orbital_macros | 0 | 0 | 0 | 0 | 0/1 | 0.00s | | orbital_material_shader | 2 | 2 | 0 | 0 | - | 0.01s | | orbital_math | 4 | 4 | 0 | 0 | - | 0.03s | | orbital_procgeo | 2 | 2 | 0 | 0 | - | 0.02s | | orbital_render_graph | 6 | 6 | 0 | 0 | - | 0.05s | | orbital_renderer | 4 | 4 | 0 | 0 | - | 0.03s | | orbital_resources | 20 | 20 | 0 | 0 | - | 2.92s | | orbital_shader_core | 0 | 0 | 0 | 0 | 1/1 | 0.00s | | orbital_shader_preprocessor | 12 | 12 | 0 | 0 | - | 0.10s | | orbital_shadow | 3 | 3 | 0 | 0 | - | 0.02s | | orbital_text | 14 | 14 | 0 | 0 | 0/1 | 0.56s | | orbital_texture | 11 | 11 | 0 | 0 | - | 0.10s | | orbital_touch_ui | 1 | 1 | 0 | 0 | 0/1 | 0.01s | | orbital_ui | 32 | 32 | 0 | 0 | 0/1 | 0.24s | | orbital_world_environment | 13 | 13 | 0 | 0 | - | 0.11s | ```mermaid pie showData title Nextest outcomes "Passed" : 428 ``` ```mermaid pie showData title Doctest outcomes "Passed" : 1 "Skipped" : 10 ``` ```mermaid xychart-beta title "Slowest crates (nextest seconds)" x-axis ["orbital", "orbital_resources", "orbital_ecs", "orbital_text", "orbital_debug_ui", "orbital_ecs_bridge", "orbital_2d", "orbital_ui"] y-axis "Seconds" 0 --> 7.3 bar [7.24, 2.92, 0.91, 0.56, 0.36, 0.33, 0.24, 0.24] ```
SakulFlee deleted branch feat/renderer-material-v2 2026-10-26 17:13:26 +00:00
Sign in to join this conversation.
No description provided.