Expand description
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 byParam, and color-space conversion.ParamandParamInfo: every parameter, including thevector3geometry 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 iterateParam::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
[dependencies]
openpbr = "0.1.0"For no_std targets, disable the default std feature and enable libm:
[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): enablescolor/std.libm: enablescolor/libmforno_stdtargets. One ofstdorlibmis required.serde: serializesParameterswith the specification’s identifiers as field names and colors as[r, g, b]arrays, andParamas its identifier. Missing fields take their defaults; unknown fields are an error.
Re-exports§
pub use color;
Structs§
- Param
Info - Metadata for one parameter, from the specification’s parameter reference.
- Parameters
- A complete set of constant OpenPBR parameter values, with colors in the
linear RGB color space
CS. - Range
- A scalar interval, applied per channel for color parameters.
- Validation
Error - A non-finite parameter value or a value outside the checked range.
Enums§
- Bound
- One end of a
Range. - Group
- Parameter group, named by the identifier prefix its parameters share.
- Kind
- Value type of a parameter, as the specification names it.
- Param
- One OpenPBR parameter.
- Param
Default - The specification’s default for a parameter.
- SetError
- Failure from
Parameters::set. - Unit
- Physical unit of a parameter.
- Value
- A constant parameter value, with colors in linear RGB space
CS.
Constants§
- SPEC_
VERSION - The OpenPBR specification version this crate implements.
Traits§
- Linear
Rgb - A linear-light RGB space suitable for OpenPBR parameter values.