henad_compute/
lib.rs

1//! Engine machinery that turns an authoring impl into something runnable.
2//!
3//! [`cpu`] and [`gpu`] each hold one backend's engines, runner and primitives. An engine state, such as
4//! [`GridModelState`](cpu::GridModelState) or [`GpuAgentState`](gpu::GpuAgentState), runs one authoring trait as a
5//! [`SimState`](henad_core::model::SimState). Both backends share [`snapshot`], [`runtime_info`],
6//! [`display_scale`] and [`fault`], and [`runner`] drives either backend's loop.
7//!
8//! [`entry`] type-erases a model behind one entry a host can list and build, and [`simulation`] builds one with
9//! checked values and steps it from a program.
10
11#![cfg_attr(docsrs, feature(doc_cfg))]
12#![warn(missing_docs)]
13// Proving a type that holds wgpu handles `Send` or `Sync` walks wgpu-core's registries, deeper than the default
14// limit of 128.
15#![recursion_limit = "256"]
16
17/// Brings in the Rust that henad-build generated from the crate's WGSL, as the modules `shader_bindings` and
18/// `binding_decls`.
19///
20/// Call it once, at the crate root of a crate whose build script runs `henad_build::ShaderBuild`. A shader at
21/// `gpu_vote/step.wgsl` below the shader root is then available as
22/// `crate::shader_bindings::gpu_vote::step::SHADER_STRING`, and its `@group(0)` declarations as
23/// `crate::binding_decls::bindings::GPU_VOTE_STEP`.
24///
25/// Generated code is not held to the caller's lints, and both modules allow every lint it trips. `unsafe_code` is the
26/// one that matters. The generator writes `unsafe impl bytemuck::Pod` and an `unsafe fn from_raw`, so a crate denies
27/// `unsafe_code` rather than forbidding it.
28///
29/// Note that the expansion fails to compile when the shared WGSL that henad-build composed the shaders against differs
30/// from the shared WGSL this crate links. Use the same 0.x of henad and henad-build.
31#[macro_export]
32macro_rules! include_shaders {
33    () => {
34        #[allow(
35            unsafe_code,
36            dead_code,
37            unused_imports,
38            unreachable_pub,
39            unused_qualifications,
40            elided_lifetimes_in_paths,
41            single_use_lifetimes,
42            clippy::all,
43            clippy::pedantic,
44            clippy::restriction,
45            clippy::nursery
46        )]
47        mod shader_bindings {
48            use $crate::__shader_support::{bytemuck, wgpu};
49            ::core::include!(::core::concat!(::core::env!("OUT_DIR"), "/shader_bindings.rs"));
50        }
51
52        #[allow(
53            unsafe_code,
54            dead_code,
55            unused_imports,
56            unreachable_pub,
57            unused_qualifications,
58            elided_lifetimes_in_paths,
59            single_use_lifetimes,
60            clippy::all,
61            clippy::pedantic,
62            clippy::restriction,
63            clippy::nursery
64        )]
65        mod binding_decls {
66            use $crate::__shader_support::{BindingDecl, BindingKind};
67            ::core::include!(::core::concat!(::core::env!("OUT_DIR"), "/binding_decls.rs"));
68        }
69
70        const _: () = ::core::assert!(
71            binding_decls::SHARED_WGSL_FNV1A64 == $crate::__shader_support::SHARED_WGSL_FNV1A64,
72            "henad-build composed these shaders against other shared WGSL than this henad links. Use the same 0.x of \
73             henad and henad-build, from one source.",
74        );
75    };
76}
77
78include_shaders!();
79
80pub mod cpu;
81pub mod display_scale;
82pub mod entry;
83pub mod fault;
84pub mod gpu;
85pub mod runner;
86pub mod runtime_info;
87pub mod simulation;
88pub mod snapshot;
89
90/// henad-compute's build, whose source hash covers its own `src` and manifest alone.
91#[doc(hidden)]
92pub const __COMPUTE_BUILD: henad_core::provenance::BuildInfo = henad_core::build_info!();
93
94/// Items that the code from [`include_shaders!`] refers to through `$crate`.
95#[doc(hidden)]
96pub mod __shader_support {
97    pub use henad_core::authoring::model::binding::{BindingDecl, BindingKind};
98    pub use henad_core::authoring::primitives::wgsl::SHARED_WGSL_FNV1A64;
99    pub use {bytemuck, wgpu};
100}
101
102/// Items that the exported macros refer to through `$crate`, so a caller needs none of them in scope.
103#[doc(hidden)]
104pub mod __macro_support {
105    pub use henad_core::authoring::model::agent_model::{AgentLanes, ChunkTally};
106    pub use henad_core::metadata::LaneSpec;
107    pub use rayon;
108
109    pub use crate::cpu::primitives::chunked::chunk_seed;
110}
henad_compute/lib.rs

henad_compute/
lib.rs
