# openpbr
The [OpenPBR Surface](https://github.com/AcademySoftwareFoundation/OpenPBR/tree/v1.1.1)
parameter set as plain, `no_std` Rust data.
- `Parameters<CS>`: 37 constant inputs with the specification's
defaults, range validation, dynamic access by `Param`, and conversion
between linear RGB color spaces.
- `Param` / `ParamInfo`: all 41 parameters of the specification's parameter
reference, including the `vector3` geometry inputs, with identifier, label,
group, type, allowed and typical ranges, default, unit, and whether the
value is a color.
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.
## 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.
## Usage
Colors are [`color`](https://crates.io/crates/color) `OpaqueColor` values
typed by their color space. OpenPBR assumes ACEScg unless a material says
otherwise, so `Parameters` defaults to `Parameters<AcesCg>`; renderers working
in linear Rec. 709 use `Parameters<LinearSrgb>` and `Parameters::convert`.
The `LinearRgb` bound supports ACEScg, ACES2065-1, and linear sRGB, with
documented requirements for custom spaces. Encoded RGB and XYZ are excluded.
```rust
use openpbr::color::{AcesCg, LinearSrgb, OpaqueColor};
use openpbr::{Param, Parameters};
let gold = Parameters::<AcesCg> {
base_metalness: 1.0,
base_color: OpaqueColor::new([0.94, 0.78, 0.37]),
specular_roughness: 0.2,
..Parameters::DEFAULT
};
assert_eq!(gold.validate(), Ok(()));
let for_renderer: Parameters<LinearSrgb> = gold.convert();
for param in Param::ALL {
let info = param.info();
println!("{} ({}) default {:?}", info.identifier, info.kind.name(), info.default);
}
```
This crate implements the [OpenPBR 1.1.1 parameter reference](https://github.com/AcademySoftwareFoundation/OpenPBR/blob/f8d6d947dfae4c9b599965a86c22826ea7a8dbfb/parametrization.md.html).
It evaluates no BSDF and reads or writes
no file format; glTF, MaterialX, and renderer bindings belong in adapters.
## Validation and color conversion
`validate()` and `violations()` require finite numeric values and enforce
specification ranges for scalars and non-color triples such as
`subsurface_radius_scale`. Chromatic colors may contain negative values or
values above one. For example, ACEScg red `[1, 0, 0]` converts to approximately
`[1.705, -0.130, -0.024]` in linear sRGB and still passes ordinary validation.
`validate_spec_ranges()` and `spec_range_violations()` additionally enforce
the specification's color bounds in the current RGB space. That converted
red fails the stricter check. Both checks reject NaN and infinities; neither
enforces typical ("norm") ranges or promises renderer support.
`ParamInfo` retains the exact OpenPBR 1.1.1 ranges. Conversion does not clip
or gamut-map colors. The application owns any gamut policy needed before
shading. Public fields, dynamic setters, and deserialization remain unchecked;
call the appropriate validation method before use.
Serde payloads contain no color-space identifier, specification version, or
scene-unit scale. The containing format supplies these. Missing fields are
default-filled, so this is a resolved parameter payload rather than a record
of authored versus unauthored inputs.
## Features
- `std` (default) or `libm`: one is required; they select `color`'s float math.
- `serde`: identifiers as field names, colors as `[r, g, b]`, missing fields
filled with defaults, and unknown fields rejected.
## Minimum supported Rust Version (MSRV)
This version of `openpbr` has been verified to compile with **Rust 1.88** and
later.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.
OpenPBR is a specification of the Academy Software Foundation; this crate is
an independent implementation of its parameter set.