vyre 0.4.0

GPU compute intermediate representation with a standard operation library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

//! WGSL lowering contract.
//!
//! This module is the contract between vyre IR and the WGSL shader that runs
//! on the GPU.  Every op's Rust CPU reference maps to a specific WGSL
//! template: buffer declarations, expression emission, atomic helpers, and
//! cast rules.  The `lower` function is the single entry point that consumes a
//! validated `Program` and produces a complete `@compute` shader string.  If
//! `lower` succeeds, the output is guaranteed to parse through `naga` and to
//! match the CPU reference semantics on every conform-certified witness.

pub mod analysis;
mod buffers;
pub(crate) mod compiler;
/// WGSL emission helpers for expressions, statements, and buffer accesses.
pub mod emit;
mod emit_wgsl;
mod ensure_output_within_limit;
mod expr;
mod helper_usage;
mod impl_lowerctx;
mod lower;
mod lower_ctx;
mod lower_no_optimize;
mod max_wgsl_output_bytes;
mod node;

pub(crate) use emit_wgsl::emit_wgsl;
pub(crate) use ensure_output_within_limit::ensure_output_within_limit;

/// Lower a validated vyre program to a complete WGSL compute shader.
///
/// This is the public contract entry point.  See [`lower::lower`] for the
/// full contract.
pub use lower::lower;
pub(crate) use lower_ctx::LowerCtx;

/// Test-only lowering that bypasses the registry certificate check.
///
/// Unit tests frequently build ad-hoc `Program` instances that are not
/// registered in the conform spec directory. Those programs legitimately
/// have no certificate, so routing them through [`lower`] would fail on
/// [`crate::ops::registry::gate::verify_program_certificate`] before ever reaching the
/// emitter. This entry point skips that gate and is gated on `cfg(test)` so
/// it is not part of the public contract.
///
/// Production code must always call [`lower`]; only use this function from
/// inside `#[cfg(test)]` blocks that verify lowering shape for programs
/// constructed inline.
///
/// # Errors
///
/// Returns [`crate::Error`] for the same reasons as [`lower`] (unsupported
/// IR nodes, cast rules, or buffer layouts). The certificate check is the
/// only gate that is skipped.
/// Lower an anonymous program that has not been through the conform
/// gate — ONLY for test harnesses and proptest generators.
///
/// Production code must always route through [`lower`], which enforces
/// the registry certificate check. This bypass exists because proptest
/// generators cannot realistically run a full conformance certification
/// per iteration.
#[inline]
pub fn lower_anonymous(program: &crate::ir::model::program::Program) -> Result<String, Error> {
    let program =
        crate::ir::inline_calls(program).map_err(|err| Error::lowering(err.to_string()))?;
    let program = crate::ir::optimize(program);
    emit_wgsl(&program)
}

/// Errors that can occur while lowering vyre IR to WGSL.
pub use crate::Error;
pub(crate) use max_wgsl_output_bytes::MAX_WGSL_OUTPUT_BYTES;