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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
// Copyright 2026 the openpbr crate Authors
// SPDX-License-Identifier: Apache-2.0 OR MIT
//! The [OpenPBR Surface] parameter set as plain Rust data.
//!
//! OpenPBR is an open, physically based über-shader specification from the
//! Academy Software Foundation. This crate implements its
//! [parameter reference] for version [`SPEC_VERSION`]:
//!
//! - [`Parameters`]: 37 constant inputs,
//! with the specification's defaults ([`Parameters::DEFAULT`]), range
//! validation, dynamic access by [`Param`], and color-space conversion.
//! - [`Param`] and [`ParamInfo`]: every parameter, including the `vector3`
//! geometry inputs, with its stable identifier, label, group, type, allowed
//! and typical ranges, default, unit, and whether it is a color. Tools that
//! pack parameters into textures or build editors iterate [`Param::ALL`].
//!
//! The four `vector3` geometry inputs (`geometry_normal`, `geometry_tangent`,
//! `geometry_coat_normal`, and `geometry_coat_tangent`) have metadata but are
//! not stored in [`Parameters`]. The renderer or adapter supplies them.
//!
//! It evaluates no BSDF and knows no file format: renderers, texture
//! generators and exporters share the vocabulary and bring their own
//! evaluation. Mapping to glTF PBR is lossy and belongs in an adapter crate.
//!
//! # Installation
//!
//! ```toml
//! [dependencies]
//! openpbr = "0.1.0"
//! ```
//!
//! For `no_std` targets, disable the default `std` feature and enable `libm`:
//!
//! ```toml
//! [dependencies]
//! openpbr = { version = "0.1.0", default-features = false, features = ["libm"] }
//! ```
//!
//! Add the `serde` feature when serialization is needed.
//!
//! # Color spaces
//!
//! Colors are [`color::OpaqueColor`] values tagged with their color space at
//! the type level. [`Parameters`] defaults to [`color::AcesCg`], the space
//! OpenPBR assumes when a material names none; a renderer working in linear
//! Rec. 709 uses `Parameters<LinearSrgb>`, and [`Parameters::convert`] moves
//! between them. [`LinearRgb`] restricts parameters to linear RGB spaces;
//! encoded RGB and XYZ are excluded. The [`color`] crate is re-exported so
//! the versions match.
//!
//! ```
//! use openpbr::color::{AcesCg, LinearSrgb, OpaqueColor};
//! use openpbr::{Param, Parameters, Value};
//!
//! // A lacquered red in the specification's default space.
//! let lacquer = Parameters::<AcesCg> {
//! base_color: OpaqueColor::new([0.4, 0.02, 0.01]),
//! coat_weight: 1.0,
//! coat_roughness: 0.1,
//! ..Parameters::DEFAULT
//! };
//! assert_eq!(lacquer.validate(), Ok(()));
//! assert_eq!(lacquer.get(Param::CoatWeight), Some(Value::Float(1.0)));
//!
//! // The same material for a renderer that shades in linear Rec. 709.
//! let rec709: Parameters<LinearSrgb> = lacquer.convert();
//! assert_eq!(rec709.coat_weight, 1.0);
//!
//! // Metadata drives generic tools.
//! let info = Param::SpecularIor.info();
//! assert_eq!(info.identifier, "specular_ior");
//! assert!(!info.range.unwrap().contains(0.0));
//! ```
//!
//! # Validation and extended RGB
//!
//! [`Parameters::validate`] requires every numeric component to be finite.
//! Scalars and non-color triples also obey their specification ranges.
//! Chromatic colors may have negative components or components above one:
//! these coordinates can result from conversion between RGB gamuts.
//! [`Parameters::validate_spec_ranges`] additionally checks color components
//! against the specification bounds in the current RGB space. Neither check
//! enforces typical ("norm") ranges or guarantees renderer support.
//!
//! ```
//! use openpbr::{Parameters, color::{AcesCg, LinearSrgb, OpaqueColor}};
//!
//! let red = Parameters::<AcesCg> {
//! base_color: OpaqueColor::new([1.0, 0.0, 0.0]),
//! ..Parameters::DEFAULT
//! };
//! assert_eq!(red.validate_spec_ranges(), Ok(()));
//! let converted: Parameters<LinearSrgb> = red.convert();
//! assert!(converted.base_color.components[0] > 1.0);
//! assert!(converted.base_color.components[1] < 0.0);
//! assert_eq!(converted.validate(), Ok(()));
//! assert!(converted.validate_spec_ranges().is_err());
//! ```
//!
//! Conversion preserves extended coordinates without clipping or gamut
//! mapping. The caller owns any gamut policy needed before shading. Public
//! fields, [`Parameters::set`], and deserialization are unchecked; validate
//! before use. Serde payloads carry no color-space identifier, specification
//! version, or scene-unit scale; the containing format supplies that context.
//!
//! # Features
//!
//! - `std` (default): enables `color/std`.
//! - `libm`: enables `color/libm` for `no_std` targets. One of `std` or
//! `libm` is required.
//! - `serde`: serializes [`Parameters`] with the specification's identifiers
//! as field names and colors as `[r, g, b]` arrays, and [`Param`] as its
//! identifier. Missing fields take their defaults; unknown fields are an
//! error.
//!
//! [OpenPBR Surface]: https://github.com/AcademySoftwareFoundation/OpenPBR/tree/v1.1.1
//! [parameter reference]: https://github.com/AcademySoftwareFoundation/OpenPBR/blob/f8d6d947dfae4c9b599965a86c22826ea7a8dbfb/parametrization.md.html
extern crate alloc;
compile_error!;
pub use color;
pub use LinearRgb;
pub use ;
pub use ;
pub use color as serde_color;
/// The OpenPBR specification version this crate implements.
///
/// Metadata follows the [parameter reference] at upstream revision
/// `f8d6d947dfae4c9b599965a86c22826ea7a8dbfb`, tagged `v1.1.1`.
///
/// [parameter reference]: https://github.com/AcademySoftwareFoundation/OpenPBR/blob/f8d6d947dfae4c9b599965a86c22826ea7a8dbfb/parametrization.md.html
pub const SPEC_VERSION: &str = "1.1.1";