Skip to main content

Crate openpbr

Crate openpbr 

Source
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 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

[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): 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.

Re-exports§

pub use color;

Structs§

ParamInfo
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.
ValidationError
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.
ParamDefault
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§

LinearRgb
A linear-light RGB space suitable for OpenPBR parameter values.