SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Portable render intent and immutable HDR references. Runtime paths, captured bodies and devices never enter a design.
use std::{fmt, marker::PhantomData};
use serde::{Deserialize, Serialize};
use solidcraft_render::{
Camera,
job::{
CpuBudget, CpuProgressiveOptions, DirectionalLightOptions, JobOptions, LightingPreset, PunctualLightOptions, RaytraceEnvironmentOptions,
RaytraceOptions, RectangleLightOptions, StudioLighting, Sun, ThinLens, ToneMap,
},
lighting::environment::SkyGradient,
};
use crate::{
DocError, Result,
render_resources::{CpuHdrEnvironment, GpuHdrEnvironment},
};
/// The selected method, not a collection of independent backend drafts.
/// Missing/null `RenderSetup.job` retains the legacy request protocol.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "method", rename_all = "snake_case", deny_unknown_fields)]
pub enum RenderJob {
Raster {
#[serde(default)]
transparent_background: bool,
},
CpuRaytrace {
#[serde(default)]
transparent_background: bool,
// Keep numerical CPU intent out of every raster/GPU enum value too.
#[serde(default)]
options: Box<CpuJob>,
},
GpuPath {
#[serde(default)]
transparent_background: bool,
// StudioLighting contains bounded inline area/directional sources; boxing keeps the other variants small.
#[serde(default)]
options: Box<GpuJob>,
},
}
impl RenderJob {
pub fn validate(&self, camera: &Camera, exposure_ev: f64) -> Result<()> {
match self {
Self::Raster { .. } if exposure_ev != 0.0 => Err(DocError::Invalid("saved raster rendering requires exposure_ev: 0".into())),
Self::Raster { .. } => Ok(()),
Self::CpuRaytrace { options, transparent_background } => {
options.validate(exposure_ev)?;
if let Some(output) = &options.output {
output
.presentation(exposure_ev, [0; 3], *transparent_background)
.validate()
.map_err(|error| DocError::Invalid(error.to_string()))?;
}
if let Some(lens) = options.lens {
lens.validate_camera(camera).map_err(|error| DocError::Invalid(error.to_string()))?;
}
Ok(())
}
Self::GpuPath { options, transparent_background } => {
if *transparent_background && options.backdrop.is_some() {
return Err(DocError::Invalid("choose a camera backdrop or transparent PNG, not both".into()));
}
options.validate(exposure_ev)?;
if *transparent_background && options.finishing.bloom.is_some_and(|b| b.active()) {
return Err(DocError::Invalid("display bloom requires opaque output".into()));
}
if camera.fov == 0.0 && options.lens.is_some_and(|lens| lens.aperture_radius_mm > 0.0) {
return Err(DocError::Invalid("saved thin-lens depth of field requires a perspective camera".into()));
}
Ok(())
}
}
}
}
/// CPU values have the runtime renderer's units and limits. Exposure belongs to RenderSetup.
/// These explicit fields exclude name/ordinal bindings and external paths; HDR refers to document bytes.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CpuJob {
#[serde(skip_serializing_if = "Option::is_none")]
pub caustics: Option<solidcraft_render::job::CausticOptions>,
#[serde(skip_serializing_if = "Option::is_none")]
pub volume: Option<solidcraft_render::job::volume::HomogeneousVolume>,
#[serde(skip_serializing_if = "Option::is_none")]
pub sun: Option<Sun>,
#[serde(skip_serializing_if = "Option::is_none")]
pub sky: Option<SkyEnvironment>,
#[serde(skip_serializing_if = "crate::render_aging::SavedAgingStack::is_empty")]
pub aging: crate::render_aging::SavedAgingStack,
#[serde(skip_serializing_if = "Option::is_none")]
pub adaptive: Option<solidcraft_render::job::adaptive::AdaptiveSampling>,
#[serde(skip_serializing_if = "Option::is_none")]
pub path: Option<solidcraft_render::job::CpuPathOptions>,
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub denoise: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub lens: Option<ThinLens>,
#[serde(skip_serializing_if = "Option::is_none")]
pub output: Option<Box<solidcraft_render::job::OutputOptions>>,
#[serde(skip_serializing_if = "CpuBudget::is_compact")]
pub budget: CpuBudget,
#[serde(skip_serializing_if = "Option::is_none")]
pub progressive: Option<CpuProgressiveOptions>,
pub primary_samples: u8,
#[serde(skip_serializing_if = "Option::is_none")]
pub preset: Option<LightingPreset>,
#[serde(deserialize_with = "directional_lights", skip_serializing_if = "Option::is_none")]
pub lights: Option<Vec<DirectionalLightOptions>>,
#[serde(deserialize_with = "punctual_lights", skip_serializing_if = "Option::is_none")]
pub punctual_lights: Option<Vec<PunctualLightOptions>>,
#[serde(deserialize_with = "area_lights", skip_serializing_if = "Option::is_none")]
pub area_lights: Option<Vec<RectangleLightOptions>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub area_samples: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub seed: Option<u32>,
pub shadows: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub environment: Option<RaytraceEnvironmentOptions>,
#[serde(skip_serializing_if = "Option::is_none")]
pub hdr: Option<CpuHdrEnvironment>,
}
impl Default for CpuJob {
fn default() -> Self {
Self {
caustics: None,
volume: None,
sun: None,
sky: None,
aging: Default::default(),
adaptive: None,
denoise: false,
path: None,
lens: None,
output: None,
budget: CpuBudget::Compact,
progressive: None,
primary_samples: 1,
preset: None,
lights: None,
punctual_lights: None,
area_lights: None,
area_samples: None,
seed: None,
shadows: true,
environment: None,
hdr: None,
}
}
}
impl CpuJob {
/// Validate saved parameters without inventing captured targets.
pub fn validate(&self, exposure_ev: f64) -> Result<()> {
self.validated_parameters(exposure_ev).map(|_| ())
}
/// Validate portable map compatibility without claiming that stable aging
/// identities have been resolved into captured runtime body indices.
pub fn validate_surface_maps(&self, exposure_ev: f64) -> Result<()> {
let options = self.validated_parameters(exposure_ev)?;
solidcraft_render::job::textures::validate_cpu_options(&options).map_err(|e| DocError::Invalid(e.to_string()))
}
/// Pure lowering, valid on hosts without a CPU raytracer. Checks bounds before cloning lists.
pub fn to_runtime(&self, exposure_ev: f64) -> Result<RaytraceOptions> {
if self.aging.iter().any(|layer| layer.target.is_some()) {
return Err(DocError::Invalid("targeted CPU aging requires stable occurrence resolution against the current scene".into()));
}
self.validated_parameters(exposure_ev)
}
fn validated_parameters(&self, exposure_ev: f64) -> Result<RaytraceOptions> {
if let Some(hdr) = self.hdr {
hdr.validate()?;
if self.environment.is_some() || self.sky.is_some() {
return Err(DocError::Invalid("choose either saved CPU HDR, gradient Sky or constant environment".into()));
}
}
bounded(&self.lights, 8, "directional lights")?;
bounded(&self.punctual_lights, 8, "point/spot lights")?;
bounded(&self.area_lights, 4, "rectangular lights")?;
if self.area_samples.is_some_and(|n| !matches!(n, 1 | 4 | 16 | 64)) {
return Err(DocError::Invalid("saved area_samples must be 1, 4, 16 or 64".into()));
}
// Preserve hidden editable intent in CpuJob, but do not submit tuning for
// a light family that is explicitly absent. This does not rewrite the file.
let active_area = self.area_lights.as_ref().is_some_and(|lights| !lights.is_empty());
let aging = self.aging.parameters_only()?;
let sky = self
.sky
.as_ref()
.map(|sky| -> Result<_> {
sky.validate()?;
let SkyEnvironment::Sky { gradient, rotation_rad, intensity } = *sky;
Ok(Box::new(solidcraft_render::job::CpuSky { gradient, rotation_rad, intensity }))
})
.transpose()?;
let options = RaytraceOptions {
caustics: self.caustics,
volume: self.volume,
sun: self.sun.map(Box::new),
sky,
aging: (!aging.is_empty()).then(|| Box::new(aging)),
adaptive: self.adaptive.map(Box::new),
denoise: self.denoise,
path: self.path,
lens: self.lens,
output: self.output.clone(),
budget: self.budget,
progressive: self.progressive,
primary_samples: self.primary_samples,
preset: self.preset,
lights: self.lights.clone(),
punctual_lights: self.punctual_lights.clone(),
area_lights: self.area_lights.clone(),
area_samples: if active_area { self.area_samples } else { None },
seed: if active_area { self.seed } else { None },
shadows: self.shadows,
environment: self.environment,
exposure_ev,
..Default::default()
};
options.validate().map_err(|e| DocError::Invalid(e.to_string()))?;
Ok(options)
}
}
/// Progressive values without a second exposure authority or captured GPU bindings.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct GpuJob {
#[serde(skip_serializing_if = "Option::is_none")]
pub caustics: Option<solidcraft_render::job::CausticOptions>,
#[serde(skip_serializing_if = "crate::render_aging::SavedAgingStack::is_empty")]
pub aging: crate::render_aging::SavedAgingStack,
pub nested_media: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub volume: Option<solidcraft_render::job::volume::HomogeneousVolume>,
#[serde(skip_serializing_if = "Option::is_none")]
pub adaptive: Option<solidcraft_render::job::adaptive::AdaptiveSampling>,
/// Conditional Fresnel strata per primary sample; one keeps the old stream.
pub transmission_samples: u32,
#[serde(skip_serializing_if = "solidcraft_render::job::finishing::Finishing::is_identity")]
pub finishing: solidcraft_render::job::finishing::Finishing,
#[serde(skip_serializing_if = "Option::is_none")]
pub backdrop: Option<solidcraft_render::job::finishing::Backdrop>,
pub linear_exr: bool,
pub samples: u32,
pub max_depth: u32,
pub seed: u32,
pub tone_map: ToneMap,
pub denoise: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub lens: Option<ThinLens>,
#[serde(skip_serializing_if = "Option::is_none")]
pub lighting: Option<StudioLighting>,
#[serde(skip_serializing_if = "Option::is_none")]
pub environment: Option<SkyEnvironment>,
#[serde(skip_serializing_if = "Option::is_none")]
pub hdr: Option<GpuHdrEnvironment>,
}
impl Default for GpuJob {
fn default() -> Self {
let options = JobOptions::default();
Self {
caustics: None,
aging: Default::default(),
nested_media: options.nested_media,
volume: options.volume,
adaptive: options.adaptive,
transmission_samples: options.transmission_samples,
finishing: options.finishing,
backdrop: options.backdrop,
linear_exr: options.linear_exr,
samples: options.samples,
max_depth: options.max_depth,
seed: options.seed,
tone_map: options.tone_map,
denoise: options.denoise,
lens: options.lens,
lighting: options.lighting,
environment: None,
hdr: None,
}
}
}
impl GpuJob {
/// Pure numerical validation; this does not resolve a saved occurrence.
pub fn validate(&self, exposure_ev: f64) -> Result<()> {
self.validated_parameters(exposure_ev).map(|_| ())
}
/// Untargeted intent is self-contained. Targeted aging requires the engine's
/// current capture; callers cannot silently turn an unresolved target global.
pub fn to_runtime(&self, exposure_ev: f64) -> Result<JobOptions> {
if self.aging.iter().any(|layer| layer.target.is_some()) {
return Err(DocError::Invalid("targeted aging requires stable occurrence resolution against the current scene".into()));
}
self.validated_parameters(exposure_ev)
}
fn validated_parameters(&self, exposure_ev: f64) -> Result<JobOptions> {
if let Some(hdr) = self.hdr {
hdr.validate()?;
if self.environment.is_some() {
return Err(DocError::Invalid("choose either saved GPU HDR or sky environment".into()));
}
}
if let Some(environment) = self.environment {
environment.validate()?;
}
let options = JobOptions {
caustics: self.caustics,
aging: self.aging.parameters_only()?,
nested_media: self.nested_media,
volume: self.volume,
adaptive: self.adaptive,
transmission_samples: self.transmission_samples,
finishing: self.finishing,
backdrop: self.backdrop,
linear_exr: self.linear_exr,
samples: self.samples,
max_depth: self.max_depth,
seed: self.seed,
tone_map: self.tone_map,
denoise: self.denoise,
lens: self.lens,
lighting: self.lighting,
exposure_ev,
};
options.validate().map_err(|e| DocError::Invalid(e.to_string()))?;
Ok(options)
}
}
/// Only the self-contained procedural sky is portable in this slice. HDR paths are rejected.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum SkyEnvironment {
Sky {
#[serde(default)]
gradient: SkyGradient,
#[serde(default)]
rotation_rad: f64,
#[serde(default = "unit")]
intensity: f64,
},
}
impl SkyEnvironment {
pub fn validate(&self) -> Result<()> {
let Self::Sky { gradient, rotation_rad, intensity } = self;
gradient.validate().map_err(|e| DocError::Invalid(e.to_string()))?;
if !rotation_rad.is_finite() || rotation_rad.abs() > 1e6 || !intensity.is_finite() || !(0.0..=100.0).contains(intensity) {
return Err(DocError::Invalid("saved sky rotation must be finite within +/-1000000 radians and intensity 0..100".into()));
}
Ok(())
}
}
fn unit() -> f64 {
1.0
}
fn bounded<T>(values: &Option<Vec<T>>, maximum: usize, label: &str) -> Result<()> {
if values.as_ref().is_some_and(|values| values.len() > maximum || values.capacity() > maximum) {
return Err(DocError::Invalid(format!("at most {maximum} saved {label} and reserved slots")));
}
Ok(())
}
// Do not deserialize unbounded Vecs and truncate them afterwards. Null and omission both
// mean unspecified; Some([]) remains an explicit empty list and is never converted to None.
fn optional_lights<'de, D, T, const N: usize>(deserializer: D) -> std::result::Result<Option<Vec<T>>, D::Error>
where
D: serde::Deserializer<'de>,
T: Deserialize<'de>,
{
struct Lights<T, const N: usize>(PhantomData<T>);
impl<'de, T: Deserialize<'de>, const N: usize> serde::de::Visitor<'de> for Lights<T, N> {
type Value = Vec<T>;
fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "at most {N} saved lights")
}
fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut sequence: A) -> std::result::Result<Self::Value, A::Error> {
let mut values = Vec::new();
values.try_reserve_exact(N).map_err(serde::de::Error::custom)?;
while let Some(value) = sequence.next_element()? {
if values.len() == N {
return Err(serde::de::Error::custom(format!("at most {N} saved lights")));
}
values.push(value);
}
Ok(values)
}
}
struct Optional<T, const N: usize>(PhantomData<T>);
impl<'de, T: Deserialize<'de>, const N: usize> serde::de::Visitor<'de> for Optional<T, N> {
type Value = Option<Vec<T>>;
fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "null or at most {N} saved lights")
}
fn visit_none<E: serde::de::Error>(self) -> std::result::Result<Self::Value, E> {
Ok(None)
}
fn visit_unit<E: serde::de::Error>(self) -> std::result::Result<Self::Value, E> {
Ok(None)
}
fn visit_some<D: serde::Deserializer<'de>>(self, deserializer: D) -> std::result::Result<Self::Value, D::Error> {
deserializer.deserialize_seq(Lights::<T, N>(PhantomData)).map(Some)
}
}
deserializer.deserialize_option(Optional::<T, N>(PhantomData))
}
fn directional_lights<'de, D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Option<Vec<DirectionalLightOptions>>, D::Error> {
optional_lights::<D, DirectionalLightOptions, 8>(d)
}
fn punctual_lights<'de, D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Option<Vec<PunctualLightOptions>>, D::Error> {
optional_lights::<D, PunctualLightOptions, 8>(d)
}
fn area_lights<'de, D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Option<Vec<RectangleLightOptions>>, D::Error> {
optional_lights::<D, RectangleLightOptions, 4>(d)
}
#[cfg(test)]
mod cpu_volume_portable_tests {
use super::*;
use solidcraft_render::job::{CpuPathOptions, CpuProgressiveOptions, volume::HomogeneousVolume};
#[test]
fn cpu_volume_saved_parameters_roundtrip_lower_without_default_adoption_or_hidden_repairs() {
let v = HomogeneousVolume {
min_mm: [-2.0, -3.0, -4.0],
max_mm: [5.0, 6.0, 7.0],
extinction_per_mm: 0.3,
scattering_albedo: [0.2, 0.4, 0.6],
anisotropy: -0.37,
};
let old = serde_json::to_value(CpuJob::default()).unwrap();
assert!(old.get("volume").is_none());
let mut job = CpuJob {
volume: Some(v),
path: Some(CpuPathOptions { max_depth: 8 }),
progressive: Some(CpuProgressiveOptions { samples_per_pixel: 4, seed: 9 }),
..Default::default()
};
let json = serde_json::to_value(&job).unwrap();
let reopened: CpuJob = serde_json::from_value(json.clone()).unwrap();
assert_eq!(reopened, job);
assert_eq!(reopened.to_runtime(0.0).unwrap().volume, Some(v));
job.denoise = true;
let before = job.clone();
assert!(job.validate(0.0).is_err());
assert_eq!(job, before);
job.denoise = false;
job.path = None;
let before = job.clone();
assert!(job.validate(0.0).is_err());
assert_eq!(job, before);
job.volume.as_mut().unwrap().extinction_per_mm = 0.0;
job.denoise = true;
job.validate(0.0).unwrap();
let inactive = serde_json::to_value(&job).unwrap();
assert_eq!(inactive["volume"]["anisotropy"], -0.37);
assert_eq!(serde_json::from_value::<CpuJob>(inactive).unwrap(), job);
job.volume = None;
job.denoise = false;
job.progressive = None;
assert_eq!(serde_json::to_value(job).unwrap(), old);
}
}