feat(billboard): add camera-facing billboard components #954

Merged
SakulFlee merged 1 commit from feat/renderer-billboards into main 2026-10-27 22:03:55 +00:00
Owner

Summary

Phase 7: camera-facing billboards.

  • New orbital_billboard crate and Billboard ECS component.
  • Modes: full camera-facing, Y-axis upright, and fixed local XY plane.
  • Per-billboard world position, size, rotation, normalized pivot and optional custom mesh.
  • Lit PBR billboards and unlit textured billboards.
  • Opaque, alpha-masked and blended variants; blended billboards use the existing sorted transparent queue.
  • Billboards are realized as ordinary models, so they reuse:
    • deferred/G-buffer for lit opaque billboards
    • forward path for unlit/opaque and transparent billboards
    • existing depth testing, frustum culling, material/mesh caches
    • model-center transparent sorting
  • BillboardModule realizes billboards into models each frame, so no renderer pass or new GPU buffer path was needed.
  • New Examples/billboards scene covers all modes, a lit billboard, and overlapping blended billboards.
  • The unlit billboard shader is validated with naga; transform/quad/material tests are included.

Verification

  • cargo fmt --all --check
  • cargo test --workspace --no-fail-fast (exit status 0)
  • cargo check --workspace with clippy-driver and -D warnings
  • 25/25 naga WGSL tests, including the new unlit billboard shader
  • cargo check -p template_billboards

GUI execution is still unavailable here (no display/GPU), so billboard orientation and sorting are compile/unit-test verified only.

Refs #781, #783.

## Summary Phase 7: camera-facing billboards. - New `orbital_billboard` crate and `Billboard` ECS component. - Modes: full camera-facing, Y-axis upright, and fixed local XY plane. - Per-billboard world position, size, rotation, normalized pivot and optional custom mesh. - Lit PBR billboards and unlit textured billboards. - Opaque, alpha-masked and blended variants; blended billboards use the existing sorted transparent queue. - Billboards are realized as ordinary models, so they reuse: - deferred/G-buffer for lit opaque billboards - forward path for unlit/opaque and transparent billboards - existing depth testing, frustum culling, material/mesh caches - model-center transparent sorting - `BillboardModule` realizes billboards into models each frame, so no renderer pass or new GPU buffer path was needed. - New `Examples/billboards` scene covers all modes, a lit billboard, and overlapping blended billboards. - The unlit billboard shader is validated with naga; transform/quad/material tests are included. ## Verification - `cargo fmt --all --check` - `cargo test --workspace --no-fail-fast` (exit status 0) - `cargo check --workspace` with clippy-driver and `-D warnings` - 25/25 naga WGSL tests, including the new unlit billboard shader - `cargo check -p template_billboards` GUI execution is still unavailable here (no display/GPU), so billboard orientation and sorting are compile/unit-test verified only. Refs #781, #783.
feat(billboard): add camera-facing billboard components
All checks were successful
Lint / lint (pull_request) Successful in 1m34s
Templates / templates (pull_request) Successful in 15m46s
PR / test (pull_request) Successful in 20m45s
12a456d6a0
Add orbital_billboard with full, Y-axis and fixed-axis modes, per-instance position/size/rotation/pivot, and lit/unlit materials. Billboards are realized as ordinary models, reusing the existing opaque/deferred, transparent sorting, depth, culling and material pipelines.

Unlit materials use a dedicated forward shader; lit billboards use PBR with a flat normal and white metallic/roughness/occlusion maps. Add an Examples/billboards scene covering all modes, a lit billboard, and overlapping blended billboards.

Validate the unlit shader with naga and add component/transform tests.

Smart test results

Result: PASS

Scope: full workspace

Reason: workspace-level change: Cargo.lock

Elapsed: 14m 31s

Workflow run

Overall: 462 tests, 452 passed, 0 failed, 10 skipped

Nextest: 451 tests, 451 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 - 8.20s
orbital_2d 29 29 0 0 0/1 0.31s
orbital_app 10 10 0 0 0/1 0.10s
orbital_billboard 5 5 0 0 - 0.05s
orbital_camera 8 8 0 0 - 0.08s
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.46s
orbital_ecs 114 114 0 0 0/2 1.18s
orbital_ecs_bridge 39 39 0 0 - 0.36s
orbital_file_manager 5 5 0 0 - 0.07s
orbital_iced 25 25 0 0 - 0.22s
orbital_importer_gltf 14 14 0 0 - 0.30s
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.02s
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 8 8 0 0 - 0.06s
orbital_resources 25 25 0 0 - 0.38s
orbital_shader_core 0 0 0 0 1/1 0.00s
orbital_shader_pbr 4 4 0 0 - 0.02s
orbital_shader_preprocessor 12 12 0 0 - 0.07s
orbital_shadow 3 3 0 0 - 0.02s
orbital_text 14 14 0 0 0/1 0.40s
orbital_texture 11 11 0 0 - 0.07s
orbital_touch_ui 1 1 0 0 0/1 0.01s
orbital_ui 32 32 0 0 0/1 0.19s
orbital_world_environment 13 13 0 0 - 0.07s
pie showData
    title Nextest outcomes
    "Passed" : 451
pie showData
    title Doctest outcomes
    "Passed" : 1
    "Skipped" : 10
xychart-beta
    title "Slowest crates (nextest seconds)"
    x-axis ["orbital", "orbital_ecs", "orbital_debug_ui", "orbital_text", "orbital_resources", "orbital_ecs_bridge", "orbital_2d", "orbital_importer_gltf"]
    y-axis "Seconds" 0 --> 8.2
    bar [8.20, 1.18, 0.46, 0.40, 0.38, 0.36, 0.31, 0.30]
<!-- orbital-ci-test-results --> ## Smart test results **Result:** PASS **Scope:** full workspace **Reason:** workspace-level change: Cargo.lock **Elapsed:** 14m 31s [Workflow run](https://forgejo.sakul-flee.de/SakulFlee/Orbital/actions/runs/735) **Overall:** 462 tests, 452 passed, 0 failed, 10 skipped **Nextest:** 451 tests, 451 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 | - | 8.20s | | orbital_2d | 29 | 29 | 0 | 0 | 0/1 | 0.31s | | orbital_app | 10 | 10 | 0 | 0 | 0/1 | 0.10s | | orbital_billboard | 5 | 5 | 0 | 0 | - | 0.05s | | orbital_camera | 8 | 8 | 0 | 0 | - | 0.08s | | 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.46s | | orbital_ecs | 114 | 114 | 0 | 0 | 0/2 | 1.18s | | orbital_ecs_bridge | 39 | 39 | 0 | 0 | - | 0.36s | | orbital_file_manager | 5 | 5 | 0 | 0 | - | 0.07s | | orbital_iced | 25 | 25 | 0 | 0 | - | 0.22s | | orbital_importer_gltf | 14 | 14 | 0 | 0 | - | 0.30s | | 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.02s | | 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 | 8 | 8 | 0 | 0 | - | 0.06s | | orbital_resources | 25 | 25 | 0 | 0 | - | 0.38s | | orbital_shader_core | 0 | 0 | 0 | 0 | 1/1 | 0.00s | | orbital_shader_pbr | 4 | 4 | 0 | 0 | - | 0.02s | | orbital_shader_preprocessor | 12 | 12 | 0 | 0 | - | 0.07s | | orbital_shadow | 3 | 3 | 0 | 0 | - | 0.02s | | orbital_text | 14 | 14 | 0 | 0 | 0/1 | 0.40s | | orbital_texture | 11 | 11 | 0 | 0 | - | 0.07s | | orbital_touch_ui | 1 | 1 | 0 | 0 | 0/1 | 0.01s | | orbital_ui | 32 | 32 | 0 | 0 | 0/1 | 0.19s | | orbital_world_environment | 13 | 13 | 0 | 0 | - | 0.07s | ```mermaid pie showData title Nextest outcomes "Passed" : 451 ``` ```mermaid pie showData title Doctest outcomes "Passed" : 1 "Skipped" : 10 ``` ```mermaid xychart-beta title "Slowest crates (nextest seconds)" x-axis ["orbital", "orbital_ecs", "orbital_debug_ui", "orbital_text", "orbital_resources", "orbital_ecs_bridge", "orbital_2d", "orbital_importer_gltf"] y-axis "Seconds" 0 --> 8.2 bar [8.20, 1.18, 0.46, 0.40, 0.38, 0.36, 0.31, 0.30] ```
SakulFlee deleted branch feat/renderer-billboards 2026-10-27 22:03:56 +00:00
Sign in to join this conversation.
No description provided.