SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Saved render intent, independent of runtime backend availability and GPU resources.
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use solidcore_record::Vec3;
use solidcraft_render::{BackendId, Camera, RenderFormat, RenderLimits, RenderMode, UpAxis};
pub use crate::render_job::{CpuJob, GpuJob, RenderJob, SkyEnvironment};
use crate::{DocError, Result};
pub const MAX_RENDER_SETUPS: usize = 32;
pub const MAX_SETUP_NAME_BYTES: usize = 128;
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RenderSetup {
pub backend: BackendId,
pub mode: RenderMode,
#[serde(deserialize_with = "SavedCamera::deserialize")]
pub camera: Camera,
pub width: u32,
pub height: u32,
pub format: RenderFormat,
pub exposure_ev: f64,
/// Legacy common environment orientation, in radians; typed jobs require 0 here.
pub environment_rotation: f64,
pub environment_intensity: f64,
/// sRGB display backplate, independent of the method's environment lighting.
pub background: [u8; 3],
/// Selected method's numerical intent and HDR reference; absent means the legacy request protocol.
#[serde(skip_serializing_if = "Option::is_none")]
pub job: Option<RenderJob>,
#[serde(skip_serializing_if = "crate::render_surface::SurfaceBindings::is_empty")]
pub surfaces: crate::render_surface::SurfaceBindings,
#[serde(skip_serializing_if = "crate::render_optics::OpticalBindings::is_empty")]
pub optics: crate::render_optics::OpticalBindings,
#[serde(skip_serializing_if = "crate::render_coat::CoatBindings::is_empty")]
pub coats: crate::render_coat::CoatBindings,
#[serde(skip_serializing_if = "solidcraft_render::stage::Stage::is_empty")]
pub stage: solidcraft_render::stage::Stage,
}
/// The CPU request a size check belongs to, so a refusal can name the profile that admits it.
#[derive(Clone, Copy)]
struct CpuSize {
progressive: Option<solidcraft_render::job::CpuProgressiveOptions>,
}
// Reuse Camera's representation and defaults, but reject misspelled saved fields. A remote
// derive constructs Camera itself, so adding a Camera field requires updating this adapter.
// Navigation/named-view deserialization keeps its existing compatibility policy.
#[derive(Deserialize)]
#[serde(remote = "Camera", deny_unknown_fields)]
struct SavedCamera {
target: Vec3,
yaw: f64,
pitch: f64,
#[serde(default)]
roll: f64,
distance: f64,
fov: f64,
#[serde(default)]
up: UpAxis,
}
impl Default for RenderSetup {
fn default() -> Self {
// The built-in descriptor owns the canonical default backend identifier.
Self {
backend: solidcraft_render::builtin_backend().id,
mode: RenderMode::Preview,
camera: Camera::default(),
width: 1024,
height: 768,
format: RenderFormat::Png,
exposure_ev: 0.0,
environment_rotation: 0.0,
environment_intensity: 1.0,
background: [236, 240, 245],
job: None,
optics: Default::default(),
coats: Default::default(),
surfaces: Default::default(),
stage: Default::default(),
}
}
}
impl RenderSetup {
pub fn validate(&self) -> Result<()> {
let (limits, cpu) = match &self.job {
Some(RenderJob::CpuRaytrace { options, .. }) => (
options.budget.image_limits(options.progressive.is_some()),
Some(CpuSize {
progressive: solidcraft_render::job::cpu_camera_sampling(options.progressive, options.adaptive, options.budget)
.map_err(|e| DocError::Invalid(e.to_string()))?,
}),
),
Some(RenderJob::GpuPath { .. }) => (solidcraft_render::job::GPU_PATH_LIMITS, None),
_ => (RenderLimits::default(), None),
};
self.validate_with_limits(limits, cpu)
}
/// Runtime CPU lowering has already moved typed options out of this setup.
/// Saving still uses validate(), so a legacy setup cannot smuggle a large profile.
pub fn validate_for_cpu(&self, budget: solidcraft_render::job::CpuBudget) -> Result<()> {
budget.validate_image(self.width, self.height, None).map_err(|e| DocError::Invalid(e.to_string()))?;
self.validate_with_limits(budget.image_limits(false), Some(CpuSize { progressive: None }))
}
/// Typed GPU options have already been lowered; retain their dimension envelope.
pub fn validate_for_gpu(&self) -> Result<()> {
self.validate_with_limits(solidcraft_render::job::GPU_PATH_LIMITS, None)
}
fn validate_with_limits(&self, limits: RenderLimits, cpu: Option<CpuSize>) -> Result<()> {
self.surfaces.validate()?;
self.optics.validate()?;
self.coats.validate()?;
if !self.coats.is_empty() && !matches!(self.job, Some(RenderJob::CpuRaytrace { .. } | RenderJob::GpuPath { .. })) {
return Err(DocError::Invalid("saved clear coats require an explicit CPU or GPU raytrace job".into()));
}
if self.coats.iter().any(|coat| self.optics.iter().any(|optics| coat.target == optics.target)) {
return Err(DocError::Invalid("clear coat and Glass cannot share a target, including zero-weight authored coats".into()));
}
match &self.job {
Some(RenderJob::CpuRaytrace { options, .. }) => {
self.optics.validate_for_cpu_path(options.path.is_some())?;
if options.volume.is_some_and(|v| v.active()) && !self.optics.is_empty() {
return Err(DocError::Invalid(
"CPU Atmosphere cannot combine with saved Glass or subsurface scattering; settings are kept".into(),
));
}
if options.denoise && self.optics.iter().any(|binding| binding.optics.subsurface.is_some_and(|s| s.active())) {
return Err(DocError::Invalid(
"CPU subsurface random walks have no surface-denoiser guides; disable denoising explicitly".into(),
));
}
}
Some(RenderJob::GpuPath { .. }) => {}
_ if !self.optics.is_empty() => return Err(DocError::Invalid("saved optics require an explicit CPU or GPU raytrace job".into())),
_ => {}
}
if self.optics.iter().any(|o| self.surfaces.iter().any(|s| s.target == o.target)) {
return Err(DocError::Invalid("saved opaque surface maps and optical boundaries cannot share a target".into()));
}
self.stage.validate().map_err(|e| DocError::Invalid(e.to_string()))?;
if !self.stage.is_empty() && matches!(self.job, Some(RenderJob::Raster { .. })) {
return Err(DocError::Invalid("passive stage geometry requires raytracing; raster cannot silently discard it".into()));
}
if !self.surfaces.is_empty() {
match &self.job {
Some(RenderJob::GpuPath { .. }) => {}
Some(RenderJob::CpuRaytrace { options, .. }) => {
if !self.optics.is_empty() && options.path.is_none() {
return Err(DocError::Invalid(
"CPU surface maps cannot combine with saved Glass; preserve the bindings and select a compatible method".into(),
));
}
options.validate_surface_maps(self.exposure_ev)?;
}
_ => {
return Err(DocError::Invalid(
"saved surfaces require an explicit CPU raytrace or GPU path job; unsupported methods cannot discard bindings".into(),
));
}
}
}
let (width, height) = (u64::from(self.width), u64::from(self.height));
if width == 0 || height == 0 {
return Err(DocError::Invalid("render output must be at least 1 × 1 pixels".into()));
}
if let Some((w, h)) = limits.fit(width, height, None)
&& (w, h) != (width, height)
{
// A CPU refusal names the profile that can render the size (#8941). It is never
// selected for the person: resolution and profile change only when they choose.
let advice = cpu.map_or_else(String::new, |cpu| {
format!("; {}", solidcraft_render::job::CpuBudget::size_advice(self.width, self.height, cpu.progressive))
});
return Err(DocError::Invalid(format!(
"render output {width} × {height} exceeds the image limits ({} pixels per side, {} pixels in all); \
the largest image at this aspect is {w} × {h}{advice}",
limits.max_dimension, limits.max_pixels
)));
}
let camera = &self.camera;
if !camera.is_valid()
|| [camera.target.x, camera.target.y, camera.target.z, camera.distance].into_iter().any(|x| x.abs() > 1e9)
|| [camera.yaw, camera.pitch, camera.roll].into_iter().any(|x| x.abs() > 1e6)
|| !camera.fov.is_finite()
|| !(0.0..std::f64::consts::PI).contains(&camera.fov)
{
return Err(DocError::Invalid("invalid render camera (finite mm/radians, positive distance, 0 <= fov < pi required)".into()));
}
if !self.exposure_ev.is_finite() || !(-32.0..=32.0).contains(&self.exposure_ev) {
return Err(DocError::Invalid("render exposure must be finite and between -32 and 32 EV".into()));
}
if !self.environment_rotation.is_finite() || self.environment_rotation.abs() > 1e6 {
return Err(DocError::Invalid("render environment rotation must be finite, bounded radians".into()));
}
if !self.environment_intensity.is_finite() || !(0.0..=100.0).contains(&self.environment_intensity) {
return Err(DocError::Invalid("render environment intensity must be finite and between 0 and 100".into()));
}
if let Some(job) = &self.job {
if self.environment_rotation != 0.0 || self.environment_intensity != 1.0 {
return Err(DocError::Invalid(
"saved job environment controls belong to job.options.environment or hdr; legacy environment_rotation/intensity must be 0/1"
.into(),
));
}
job.validate(&self.camera, self.exposure_ev)?;
if let RenderJob::CpuRaytrace { options, .. } = job {
if options.denoise {
solidcraft_render::job::validate_cpu_denoise_image(self.width, self.height).map_err(|e| DocError::Invalid(e.to_string()))?;
}
options
.budget
.validate_image(
self.width,
self.height,
solidcraft_render::job::cpu_camera_sampling(options.progressive, options.adaptive, options.budget)
.map_err(|e| DocError::Invalid(e.to_string()))?,
)
.map_err(|e| DocError::Invalid(e.to_string()))?;
if let Some(output) = &options.output {
output.validate_image(self.width, self.height).map_err(|e| DocError::Invalid(e.to_string()))?;
}
}
}
// Desired mode/format/backend may be unavailable on this host. Saving intent is not preflight.
Ok(())
}
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "UncheckedSettings")]
pub struct RenderSettings {
pub setups: BTreeMap<String, RenderSetup>,
#[serde(skip_serializing_if = "crate::render_resources::HdrResources::is_empty")]
pub resources: crate::render_resources::HdrResources,
#[serde(skip_serializing_if = "crate::render_texture_resources::TextureResources::is_empty")]
pub texture_resources: crate::render_texture_resources::TextureResources,
}
#[derive(Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
struct UncheckedSettings {
setups: BTreeMap<String, RenderSetup>,
resources: crate::render_resources::HdrResources,
texture_resources: crate::render_texture_resources::TextureResources,
}
impl TryFrom<UncheckedSettings> for RenderSettings {
type Error = DocError;
fn try_from(value: UncheckedSettings) -> Result<Self> {
let settings = Self { setups: value.setups, resources: value.resources, texture_resources: value.texture_resources };
settings.validate()?;
Ok(settings)
}
}
impl RenderSettings {
pub fn is_empty(&self) -> bool {
self.setups.is_empty() && self.resources.is_empty() && self.texture_resources.is_empty()
}
pub fn validate_name(name: &str) -> Result<()> {
if name.trim().is_empty() || name != name.trim() || name.len() > MAX_SETUP_NAME_BYTES || name.chars().any(char::is_control) {
return Err(DocError::Invalid("render setup name must be trimmed, nonempty, at most 128 bytes and contain no control characters".into()));
}
Ok(())
}
pub fn validate(&self) -> Result<()> {
if self.setups.len() > MAX_RENDER_SETUPS {
return Err(DocError::Invalid("too many render setups (maximum 32)".into()));
}
for (name, setup) in &self.setups {
Self::validate_name(name)?;
setup.validate()?;
self.validate_resources(setup)?;
}
Ok(())
}
pub fn validate_resources(&self, setup: &RenderSetup) -> Result<()> {
for surface in setup.surfaces.iter() {
if let crate::render_surface::SurfaceSource::Embedded(source) = &surface.source {
for (role, id) in source.role_resources() {
let resource = self.texture_resources.required(&id)?;
resource.validate_role(role)?;
if matches!(setup.job, Some(RenderJob::CpuRaytrace { .. })) {
resource.validate_cpu_encoding()?;
}
}
}
}
match &setup.job {
Some(RenderJob::CpuRaytrace { options, .. }) => {
if let Some(hdr) = options.hdr {
hdr.validate_resource(&self.resources)?;
}
}
Some(RenderJob::GpuPath { options, .. }) => {
if let Some(hdr) = options.hdr {
hdr.validate_resource(&self.resources)?;
}
}
_ => {}
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::Document;
use std::sync::Arc;
#[test]
fn saved_light_coordinates_are_admitted_only_when_the_document_can_reopen() {
use serde_json::json;
for coordinate in [-1e9, 1e9] {
let variants = [
json!({"method":"cpu_raytrace","options":{"punctual_lights":[{
"position_mm":[coordinate,0.0,0.0],"color":[1.0,1.0,1.0],"intensity":1.0,
"reference_distance_mm":100.0,"minimum_distance_mm":0.001}]}}),
json!({"method":"gpu_path","options":{"lighting":{"area_lights":[{
"center":[coordinate,0.0,0.0],"u":[1.0,0.0,0.0],"v":[0.0,1.0,0.0],"radiance":[1.0,1.0,1.0]}]}}}),
json!({"method":"cpu_raytrace","options":{"lights":[{
"direction":[coordinate,0.0,0.0],"color":[1.0,1.0,1.0],"intensity":1.0}]}}),
];
for job in variants {
let settings: RenderSettings = serde_json::from_value(json!({"setups":{"Bounds":{"job":job}}})).unwrap();
settings.validate().unwrap();
let document = Document { render: Arc::new(settings), ..Default::default() };
assert_eq!(Document::from_json(&document.to_json()).unwrap(), document);
}
}
for coordinate in [-5e9, 5e9, 1e9_f64.next_up()] {
let mut point: solidcraft_render::job::PunctualLightOptions = serde_json::from_value(json!({
"position_mm":[coordinate,0.0,0.0],"color":[1.0,1.0,1.0],"intensity":1.0,
"reference_distance_mm":100.0,"minimum_distance_mm":0.001}))
.unwrap();
assert!(point.validate().is_err());
point.position_mm = [0.0; 3];
point.cone = Some(solidcraft_render::job::SpotConeOptions {
emitted_axis: [coordinate, 0.0, 0.0],
inner_half_angle_radians: 0.1,
outer_half_angle_radians: 0.5,
});
assert!(point.validate().is_err());
let area =
solidcraft_render::job::AreaLight { center: [coordinate, 0.0, 0.0], u: [1.0, 0.0, 0.0], v: [0.0, 1.0, 0.0], radiance: [1.0; 3] };
assert!(area.validate().is_err());
let frame = solidcraft_render::job::textures::PlanarFrame { origin: [coordinate, 0.0, 0.0], u: [1.0, 0.0, 0.0], v: [0.0, 1.0, 0.0] };
assert!(frame.validate().is_err());
}
}
fn hdr_fixture(pixel: u8) -> Vec<u8> {
let mut bytes = b"#?RADIANCE\nFORMAT=32-bit_rle_rgbe\nPRIMARIES=0.64 0.33 0.30 0.60 0.15 0.06 0.3127 0.3290\n\n-Y 2 +X 4\n".to_vec();
for _ in 0..8 {
bytes.extend_from_slice(&[pixel, 64, 32, 129]);
}
bytes
}
#[test]
fn embedded_hdr_resources_roundtrip_share_bytes_and_keep_numerical_intent() {
use crate::render_resources::{CpuHdrEnvironment, GpuHdrEnvironment, HdrResource};
let resource = HdrResource::new(hdr_fixture(128)).unwrap();
let id = resource.id();
let mut settings = RenderSettings::default();
settings.resources.insert(resource).unwrap();
settings.setups.insert(
"CPU".into(),
RenderSetup {
exposure_ev: 1.25,
job: Some(RenderJob::CpuRaytrace {
transparent_background: false,
options: Box::new(CpuJob {
lights: Some(Vec::new()),
hdr: Some(CpuHdrEnvironment { resource: id, rotation_rad: 0.75, intensity: 2.0, samples: 64 }),
..Default::default()
}),
}),
..Default::default()
},
);
settings.setups.insert(
"GPU".into(),
RenderSetup {
exposure_ev: -2.0,
job: Some(RenderJob::GpuPath {
transparent_background: true,
options: Box::new(GpuJob {
samples: 37,
hdr: Some(GpuHdrEnvironment { resource: id, rotation_rad: -0.5, intensity: 3.0, assume_linear_srgb: false }),
..Default::default()
}),
}),
..Default::default()
},
);
settings.validate().unwrap();
let cloned = settings.clone();
assert!(std::ptr::eq(settings.resources.required(&id).unwrap().bytes().as_ptr(), cloned.resources.required(&id).unwrap().bytes().as_ptr()));
let document = Document { render: Arc::new(settings), ..Default::default() };
let reopened = Document::from_json(&document.to_json()).unwrap();
assert_eq!(document, reopened);
assert_eq!(reopened.render.resources.len(), 1);
let legacy: RenderSettings = serde_json::from_str(r#"{"setups":{"Old":{}}}"#).unwrap();
assert!(legacy.resources.is_empty());
assert!(legacy.setups["Old"].job.is_none());
let mut missing = serde_json::to_value(&document).unwrap();
missing["render"]["resources"] = serde_json::json!({});
assert!(Document::from_json(&missing.to_string()).unwrap_err().to_string().contains("missing embedded HDR"));
}
#[test]
fn embedded_hdr_parse_rejects_hash_type_paths_noncanonical_payload_and_counts() {
use crate::render_resources::{HdrResource, HdrResources, MAX_HDR_BYTES};
use serde_json::json;
let source = HdrResource::new(hdr_fixture(128)).unwrap();
let id = source.id().to_string();
let valid = serde_json::to_value(&source).unwrap();
for (key, value) in [
("kind", json!("png")),
("data", json!("")),
("data", json!(format!("{}\n", source.base64().unwrap()))),
("data", json!("AA==")),
("path", json!("original.hdr")),
("hdr_blob", json!("blobs/not-in-plain-json.hdr")),
] {
let mut resource = valid.clone();
resource[key] = value;
assert!(serde_json::from_value::<HdrResources>(json!({(id.clone()):resource})).is_err(), "{key}");
}
assert!(serde_json::from_value::<HdrResources>(json!({("0".repeat(64)):valid})).unwrap_err().to_string().contains("hash mismatch"));
let duplicate = format!("{{\"{id}\":{valid},\"{id}\":{valid}}}");
assert!(serde_json::from_str::<HdrResources>(&duplicate).unwrap_err().to_string().contains("duplicate"));
let duplicate_document = format!("{{\"render\":{{\"resources\":{duplicate}}}}}");
assert!(Document::from_json(&duplicate_document).unwrap_err().to_string().contains("duplicate"));
let mut many = serde_json::Map::new();
for pixel in 0..64 {
let resource = HdrResource::new(hdr_fixture(pixel)).unwrap();
many.insert(resource.id().to_string(), json!(resource));
}
assert!(serde_json::from_value::<HdrResources>(serde_json::Value::Object(many.clone())).is_ok());
many.insert("f".repeat(64), json!({"kind":"radiance_hdr","data":"invalid"}));
assert!(serde_json::from_value::<HdrResources>(serde_json::Value::Object(many)).unwrap_err().to_string().contains("too many"));
let oversized = json!({(id):{"kind":"radiance_hdr","data":"A".repeat(MAX_HDR_BYTES.div_ceil(3)*4+4)}});
assert!(Document::from_json(&json!({"render":{"resources":oversized}}).to_string()).unwrap_err().to_string().contains("budget"));
assert!(serde_json::from_value::<HdrResources>(oversized).unwrap_err().to_string().contains("budget"));
}
#[test]
fn embedded_hdr_parser_debits_aggregate_before_decoding_the_next_source() {
use crate::render_resources::{HdrId, HdrResources, MAX_HDR_BYTES, encode_hdr_base64};
use serde::de::value::{Error, MapDeserializer};
// One borrowed base64 buffer supplies distinct valid prefixes: this exercises the
// real aggregate visitor without constructing a >100 MiB JSON value/string tree.
let mut bytes = hdr_fixture(128);
bytes.resize(MAX_HDR_BYTES - 1, 0);
let encoded = encode_hdr_base64(&bytes).unwrap();
assert!(!encoded.ends_with('='));
let sources: Vec<_> = (0..5)
.map(|i| {
let length = bytes.len() - 3 * i;
(HdrId::of(&bytes[..length]).to_string(), &encoded[..encoded.len() - 4 * i])
})
.collect();
let entries =
sources.iter().map(|(id, data)| (id.as_str(), MapDeserializer::<_, Error>::new([("kind", "radiance_hdr"), ("data", *data)].into_iter())));
let error = HdrResources::deserialize(MapDeserializer::<_, Error>::new(entries)).unwrap_err().to_string();
assert!(error.contains("budget"), "{error}");
}
#[test]
fn embedded_hdr_json_probe_bounds_escaped_base64_before_value_or_string_materialization() {
use crate::render_resources::{HdrResource, MAX_HDR_BYTES};
let source = HdrResource::new(hdr_fixture(128)).unwrap();
let id = source.id().to_string();
let encoded = source.base64().unwrap();
let escaped = format!("\\u{:04x}{}", encoded.as_bytes()[0], &encoded[1..]);
let mut document = serde_json::to_value(Document::default()).unwrap();
document["render"] = serde_json::json!({"setups":{},"resources":{(id.clone()):source}});
let wire = document.to_string().replacen(&encoded, &escaped, 1);
assert_eq!(Document::from_json(&wire).unwrap().render.resources.len(), 1, "legal bounded JSON escapes retain the same payload");
// One escape makes deserialize_str require owned scratch. The borrowed RawValue
// admission scans this oversized logical base64 without that unescaped allocation.
let tail = "A".repeat(MAX_HDR_BYTES.div_ceil(3) * 4);
let oversized = format!("{{\"render\":{{\"resources\":{{\"{id}\":{{\"kind\":\"radiance_hdr\",\"data\":\"\\u0041{tail}\"}}}}}}}}");
assert!(Document::from_json(&oversized).unwrap_err().to_string().contains("budget"));
let legacy: serde_json::Value = serde_json::from_str("{\"setups\":{}}").unwrap();
assert!(serde_json::from_value::<RenderSettings>(legacy).is_ok());
assert!(serde_json::from_value::<RenderSettings>(serde_json::Value::Null).is_err());
assert!(Document::from_json("{\"render\":null}").is_err());
}
#[test]
fn embedded_hdr_references_enforce_method_color_and_environment_controls() {
use crate::render_resources::{CpuHdrEnvironment, GpuHdrEnvironment, HdrResource, HdrResources};
let declared = hdr_fixture(128);
let mut undeclared = b"#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 2 +X 4\n".to_vec();
undeclared.extend_from_slice(&declared[declared.len() - 32..]);
let mut resources = HdrResources::default();
let id = resources.insert(HdrResource::new(undeclared).unwrap()).unwrap();
let mut cpu = CpuHdrEnvironment { resource: id, rotation_rad: 0.0, intensity: 1.0, samples: 16 };
assert!(cpu.validate_resource(&resources).unwrap_err().to_string().contains("primaries"));
let mut gpu = GpuHdrEnvironment { resource: id, rotation_rad: 0.0, intensity: 1.0, assume_linear_srgb: false };
assert!(gpu.validate_resource(&resources).is_err());
gpu.assume_linear_srgb = true;
gpu.validate_resource(&resources).unwrap();
cpu.resource = resources.insert(HdrResource::new(declared).unwrap()).unwrap();
cpu.validate_resource(&resources).unwrap();
for samples in [0, 3, 65] {
cpu.samples = samples;
assert!(cpu.validate().is_err());
}
cpu.samples = 16;
cpu.intensity = 65.0;
assert!(cpu.validate().is_err());
gpu.intensity = 100.0;
gpu.validate().unwrap();
gpu.rotation_rad = f64::NAN;
assert!(gpu.validate().is_err());
let cpu_job = CpuJob {
hdr: Some(CpuHdrEnvironment { intensity: 1.0, ..cpu }),
environment: Some(solidcraft_render::job::RaytraceEnvironmentOptions { color: [0.0; 3], intensity: 0.0 }),
..Default::default()
};
assert!(cpu_job.to_runtime(0.0).is_err());
let gpu_job = GpuJob {
hdr: Some(GpuHdrEnvironment { rotation_rad: 0.0, ..gpu }),
environment: Some(SkyEnvironment::Sky { gradient: Default::default(), rotation_rad: 0.0, intensity: 1.0 }),
..Default::default()
};
assert!(gpu_job.to_runtime(0.0).is_err());
}
#[test]
fn camera_fields_are_strict_without_changing_existing_camera_defaults() {
let mut camera = serde_json::to_value(Camera::default()).unwrap();
camera["fov_degrees"] = serde_json::json!(45);
let saved = serde_json::json!({"setups":{"Studio":{"camera":camera}}});
let mut doc = serde_json::to_value(Document::default()).unwrap();
doc["render"] = saved.clone();
assert!(Document::from_json(&doc.to_string()).is_err());
assert!(serde_json::from_value::<RenderSettings>(saved).is_err());
camera.as_object_mut().unwrap().remove("fov_degrees");
camera.as_object_mut().unwrap().remove("roll");
camera.as_object_mut().unwrap().remove("up");
let setup: RenderSetup = serde_json::from_value(serde_json::json!({"camera":camera})).unwrap();
assert_eq!(setup.camera, Camera::default());
}
#[test]
fn legacy_and_named_setups_round_trip_without_changing_other_data() {
let old = Document::new("Legacy");
let mut json = serde_json::to_value(&old).unwrap();
json["format"] = serde_json::json!("solidcraft/16");
json.as_object_mut().unwrap().remove("render");
let mut loaded = Document::from_json(&json.to_string()).unwrap();
assert!(loaded.render.is_empty());
assert_eq!(loaded.format, crate::format::format_string(crate::format::FORMAT));
// Upstream owns 19 for editable offsets; saved render intent needs 20.
for version in [17, 18, 19] {
json["format"] = serde_json::json!(crate::format::format_string(version));
assert_eq!(Document::from_json(&json.to_string()).unwrap(), loaded);
}
let before = loaded.clone();
let setup = RenderSetup {
backend: serde_json::from_value(serde_json::json!("future-backend")).unwrap(),
exposure_ev: 2.5,
mode: RenderMode::Final,
format: RenderFormat::Exr,
camera: Camera { up: solidcraft_render::UpAxis::Y, ..Default::default() },
..Default::default()
};
Arc::make_mut(&mut loaded.render).setups.insert("Studio".into(), setup);
assert!(loaded.differs_only_in_render(&before));
assert_eq!(Document::from_json(&loaded.to_json()).unwrap(), loaded);
let mut previous_draft = serde_json::to_value(&loaded).unwrap();
previous_draft["format"] = serde_json::json!("solidcraft/17");
assert_eq!(Document::from_json(&previous_draft.to_string()).unwrap(), loaded);
loaded.units = "in".into();
assert!(!loaded.differs_only_in_render(&before));
}
#[test]
fn mixed_document_changes_never_qualify_as_render_only() {
let before = Document::default();
let mut render_only = before.clone();
Arc::make_mut(&mut render_only.render).setups.insert("Studio".into(), RenderSetup::default());
assert!(render_only.differs_only_in_render(&before));
for (key, value) in [
("marker", serde_json::json!(0)),
("materials", serde_json::json!({"Body1":"Steel"})),
("visibility", serde_json::json!({"hidden_bodies":["Body1"]})),
("body_components", serde_json::json!({"Body1":1})),
("next_id", serde_json::json!(99)),
] {
let mut json = serde_json::to_value(&render_only).unwrap();
json[key] = value;
let mixed: Document = serde_json::from_value(json).unwrap();
assert!(!mixed.differs_only_in_render(&before), "{key}");
}
}
#[test]
fn oversized_output_names_the_limits_and_the_largest_size() {
let setup = RenderSetup { width: 4096, height: 4096, ..Default::default() };
let message = setup.validate().unwrap_err().to_string();
assert!(message.contains("4096 × 4096 exceeds the image limits (4096 pixels per side, 4194304 pixels in all)"), "{message}");
assert!(message.contains("the largest image at this aspect is 2048 × 2048"), "{message}");
let setup = RenderSetup { width: 7680, height: 4320, ..Default::default() };
let message = setup.validate().unwrap_err().to_string();
assert!(message.contains("the largest image at this aspect is 27"), "{message}");
assert!(!message.contains("CPU resource profile"), "a raster refusal names no CPU profile: {message}");
assert!(RenderSetup { width: 2048, height: 2048, ..Default::default() }.validate().is_ok());
}
/// #8941: 4K UHD under the default Compact profile names Studio, the profile that renders it;
/// a 16K-wide image under Studio names Workstation; past Workstation no profile is named.
/// The saved profile is never changed by the check, and GPU path tracing keeps its own limits.
#[test]
fn a_cpu_size_refusal_names_the_profile_that_can_render_it() {
use solidcraft_render::job::CpuBudget;
let cpu = |budget, width, height| RenderSetup {
width,
height,
job: Some(RenderJob::CpuRaytrace { transparent_background: false, options: Box::new(CpuJob { budget, ..Default::default() }) }),
..Default::default()
};
let compact = cpu(CpuBudget::Compact, 3840, 2160);
let message = compact.validate().unwrap_err().to_string();
assert!(message.contains("3840 × 2160 exceeds the image limits (4096 pixels per side, 4194304 pixels in all)"), "{message}");
assert!(message.contains("the largest image at this aspect is 2730 × 1536"), "{message}");
assert!(message.contains("choose the Studio CPU resource profile, or a smaller size"), "{message}");
assert!(matches!(&compact.job, Some(RenderJob::CpuRaytrace { options, .. }) if options.budget == CpuBudget::Compact));
let message = compact.validate_for_cpu(CpuBudget::Compact).unwrap_err().to_string();
assert!(message.contains("choose the Studio CPU resource profile"), "{message}");
cpu(CpuBudget::Studio, 3840, 2160).validate().unwrap();
RenderSetup { width: 3840, height: 2160, ..Default::default() }.validate_for_cpu(CpuBudget::Studio).unwrap();
let message = cpu(CpuBudget::Studio, 15360, 4320).validate().unwrap_err().to_string();
assert!(message.contains("choose the Workstation CPU resource profile"), "{message}");
cpu(CpuBudget::Workstation, 15360, 4320).validate().unwrap();
let message = cpu(CpuBudget::Workstation, 16384, 16384).validate().unwrap_err().to_string();
assert!(message.contains("no CPU resource profile accepts this size; choose a smaller size"), "{message}");
for profile in ["Compact", "Studio", "Workstation"] {
assert!(!message.contains(&format!("the {profile} CPU")), "{message}");
}
// GPU path tracing: 4K renders, an over-limit size names no CPU profile.
let gpu = |width, height| RenderSetup {
width,
height,
job: Some(RenderJob::GpuPath { transparent_background: false, options: Default::default() }),
..Default::default()
};
gpu(3840, 2160).validate().unwrap();
gpu(3840, 2160).validate_for_gpu().unwrap();
let message = gpu(8193, 8193).validate().unwrap_err().to_string();
assert!(message.contains("(8192 pixels per side, 16777216 pixels in all)"), "{message}");
assert!(!message.contains("CPU resource profile"), "{message}");
}
#[test]
fn portable_jobs_preserve_complete_numerical_intent_and_legacy_omission() {
use serde_json::json;
let camera = Camera { fov: 0.75, ..Default::default() };
let wire = json!({"setups":{
"Legacy":{"exposure_ev":2,"environment_rotation":0.75,"environment_intensity":3},
"CPU":{"exposure_ev":1.25,"job":{"method":"cpu_raytrace","options":{
"primary_samples":4,"lights":[],"shadows":false,
"punctual_lights":[{"position_mm":[1,2,30],"color":[1,0.2,0.5],"intensity":2,"reference_distance_mm":50,"minimum_distance_mm":0.1,
"cone":{"emitted_axis":[0,0,-1],"inner_half_angle_radians":0.1,"outer_half_angle_radians":0.5}}],
"area_lights":[{"center_mm":[3,4,50],"edge_u_mm":[20,0,0],"edge_v_mm":[0,-10,0],"color":[0.2,0.4,1],"intensity":3}],
"area_samples":64,"seed":u32::MAX,"environment":{"color":[0.1,0.2,0.3],"intensity":0.5}
}}},
"GPU":{"camera":camera,"exposure_ev":-3.5,"job":{"method":"gpu_path","transparent_background":true,"options":{
"samples":4096,"max_depth":16,"seed":81,"tone_map":"aces_fitted","denoise":true,
"lens":{"aperture_radius_mm":0.4,"focus_distance_mm":90},
"lighting":{"environment":[0.1,0.25,0.6],"sun":{"direction":[1,-1,-2],"angular_radius_rad":0.1,"radiance":[5,4,3]},
"area_lights":[{"center":[10,20,30],"u":[4,0,0],"v":[0,-2,0],"radiance":[3,2,1]}]},
"environment":{"kind":"sky","rotation_rad":0.3,"intensity":2,"gradient":{"zenith":[0.1,0.2,0.3],"horizon":[0.4,0.5,0.6],"ground":[0.7,0.8,0.9]}}
}}}
}});
let settings: RenderSettings = serde_json::from_value(wire).unwrap();
let document = Document { render: Arc::new(settings.clone()), ..Default::default() };
let reopened = Document::from_json(&document.to_json()).unwrap();
assert_eq!(reopened, document);
let saved = serde_json::to_value(&reopened.render).unwrap();
assert!(saved["setups"]["Legacy"].get("job").is_none());
assert_eq!(saved["setups"]["Legacy"]["environment_rotation"], 0.75);
let RenderJob::CpuRaytrace { options, .. } = settings.setups["CPU"].job.as_ref().unwrap() else { panic!("CPU intent changed") };
let runtime = options.to_runtime(settings.setups["CPU"].exposure_ev).unwrap();
assert_eq!(runtime.exposure_ev, 1.25);
assert_eq!(runtime.area_samples, Some(64));
assert_eq!(runtime.seed, Some(u32::MAX));
assert!(runtime.lights.as_ref().unwrap().is_empty());
assert!(runtime.punctual_lights.as_ref().unwrap()[0].cone.is_some());
let RenderJob::GpuPath { options, transparent_background } = settings.setups["GPU"].job.as_ref().unwrap() else {
panic!("GPU intent changed")
};
assert!(*transparent_background);
let runtime = options.to_runtime(settings.setups["GPU"].exposure_ev).unwrap();
assert_eq!(runtime.exposure_ev, -3.5);
assert_eq!(runtime.lighting.unwrap().environment, [0.1, 0.25, 0.6]);
assert!(runtime.denoise);
assert!(saved["setups"]["GPU"]["job"]["options"].get("exposure_ev").is_none());
}
#[test]
fn portable_job_options_keep_null_distinct_from_explicit_empty_or_black() {
use serde_json::json;
for options in [json!({}), json!({"lights":null,"punctual_lights":null,"area_lights":null,"environment":null})] {
let setup: RenderSetup = serde_json::from_value(json!({"job":{"method":"cpu_raytrace","options":options}})).unwrap();
setup.validate().unwrap();
assert_eq!(setup.job, Some(RenderJob::CpuRaytrace { transparent_background: false, options: Box::default() }));
}
let empty: RenderSetup = serde_json::from_value(json!({"job":{"method":"cpu_raytrace","options":{"lights":[]}}})).unwrap();
empty.validate().unwrap();
assert_ne!(empty.job, Some(RenderJob::CpuRaytrace { transparent_background: false, options: Box::default() }));
for (lighting, explicit) in [(serde_json::Value::Null, false), (json!({"environment":[0,0,0],"area_lights":[]}), true)] {
let setup: RenderSetup = serde_json::from_value(json!({"job":{"method":"gpu_path","options":{"lighting":lighting}}})).unwrap();
setup.validate().unwrap();
let RenderJob::GpuPath { options, .. } = setup.job.unwrap() else { panic!("GPU intent changed") };
assert_eq!(options.lighting.is_some(), explicit);
}
let legacy: RenderSetup = serde_json::from_value(json!({"job":null,"exposure_ev":22})).unwrap();
legacy.validate().unwrap();
assert!(legacy.job.is_none());
}
#[test]
fn progressive_cpu_intent_roundtrips_offline_and_validates_the_image_work_bound() {
use serde_json::json;
let saved = json!({"setups":{"Film":{"width":512,"height":512,"exposure_ev":1.5,
"job":{"method":"cpu_raytrace","options":{"progressive":{"samples_per_pixel":64,"seed":u32::MAX},"lights":[]}}
}}});
let settings: RenderSettings = serde_json::from_value(saved.clone()).unwrap();
let document = Document { render: Arc::new(settings), ..Default::default() };
let reopened = Document::from_json(&document.to_json()).unwrap();
assert_eq!(document, reopened);
let RenderJob::CpuRaytrace { options, .. } = reopened.render.setups["Film"].job.as_ref().unwrap() else { panic!("method changed") };
let runtime = options.to_runtime(1.5).unwrap();
assert_eq!(runtime.progressive.unwrap().seed, u32::MAX);
assert_eq!(runtime.exposure_ev, 1.5);
assert_eq!(runtime.primary_samples, 1);
for (width, height, samples) in [(1025, 1024, 1), (1024, 1024, 17), (512, 512, 65), (16, 16, 0)] {
let mut invalid = saved.clone();
invalid["setups"]["Film"]["width"] = json!(width);
invalid["setups"]["Film"]["height"] = json!(height);
invalid["setups"]["Film"]["job"]["options"]["progressive"]["samples_per_pixel"] = json!(samples);
assert!(serde_json::from_value::<RenderSettings>(invalid).is_err());
}
let mut incompatible = saved;
incompatible["setups"]["Film"]["job"]["options"]["primary_samples"] = json!(4);
assert!(serde_json::from_value::<RenderSettings>(incompatible).is_err());
}
#[test]
fn cpu_transparent_intent_roundtrips_offline_and_keeps_opaque_defaults() {
use serde_json::json;
let opaque: RenderSetup = serde_json::from_value(json!({"job":{"method":"cpu_raytrace"}})).unwrap();
assert!(matches!(opaque.job, Some(RenderJob::CpuRaytrace { transparent_background: false, .. })));
let setup: RenderSetup =
serde_json::from_value(json!({"width":8,"height":8,"job":{"method":"cpu_raytrace","transparent_background":true,"options":{
"primary_samples":4,"output":{"linear_exr":true}}}}))
.unwrap();
setup.validate().unwrap();
let document = Document {
render: Arc::new(RenderSettings { setups: std::collections::BTreeMap::from([("Cutout".into(), setup)]), ..Default::default() }),
..Default::default()
};
assert_eq!(document, Document::from_json(&document.to_json()).unwrap());
for output in [json!({"backdrop":{}}), json!({"finishing":{"bloom":{"strength":1}}}), json!({"finishing":{"photographic":{"grain":0.03}}})] {
let settings = json!({"setups":{"Cutout":{"job":{"method":"cpu_raytrace","transparent_background":true,"options":{"output":output}}}}});
let error = serde_json::from_value::<RenderSettings>(settings.clone()).unwrap_err();
assert!(error.to_string().contains("opaque"), "valid opaque-only effects remain authored and refused");
let mut saved: serde_json::Value = serde_json::from_str(&Document::default().to_json()).unwrap();
saved["render"] = settings;
let error = Document::from_json(&saved.to_string()).unwrap_err();
assert!(error.to_string().contains("opaque"), "the full document loader must enforce the same saved output contract");
}
assert!(
serde_json::from_value::<RenderSetup>(json!({"job":{"method":"cpu_raytrace","options":{"transparent_background":true}}})).is_err(),
"one alpha authority beside the numerical job"
);
}
#[test]
fn cpu_physical_lens_roundtrips_offline_and_keeps_disabled_legacy_intent() {
use serde_json::json;
let camera = Camera { fov: 0.7, distance: 20.0, ..Default::default() };
let saved = json!({"setups":{"Focus":{"width":64,"height":32,"camera":camera,
"job":{"method":"cpu_raytrace","options":{"progressive":{"samples_per_pixel":8,"seed":81},
"lens":{"aperture_radius_mm":0.5,"focus_distance_mm":20.0}}}}}});
let settings: RenderSettings = serde_json::from_value(saved.clone()).unwrap();
let document = Document { render: Arc::new(settings), ..Default::default() };
assert_eq!(document, Document::from_json(&document.to_json()).unwrap());
let RenderJob::CpuRaytrace { options, .. } = document.render.setups["Focus"].job.as_ref().unwrap() else { panic!("CPU method changed") };
assert_eq!(options.to_runtime(1.5).unwrap().lens, options.lens);
let mut fixed = saved.clone();
fixed["setups"]["Focus"]["job"]["options"].as_object_mut().unwrap().remove("progressive");
assert!(serde_json::from_value::<RenderSettings>(fixed.clone()).is_err());
fixed["setups"]["Focus"]["job"]["options"]["lens"]["aperture_radius_mm"] = json!(0);
fixed["setups"]["Focus"]["camera"]["fov"] = json!(0);
let zero: RenderSettings = serde_json::from_value(fixed).unwrap();
assert_eq!(serde_json::to_value(&zero).unwrap()["setups"]["Focus"]["job"]["options"]["lens"]["aperture_radius_mm"].as_f64(), Some(0.0));
for lens in [
json!({"aperture_radius_mm":-1,"focus_distance_mm":20}),
json!({"aperture_radius_mm":0.5,"focus_distance_mm":0}),
json!({"aperture_radius_mm":0.5,"focus_distance_mm":20,"f_stop":2}),
] {
let mut invalid = saved.clone();
invalid["setups"]["Focus"]["job"]["options"]["lens"] = lens;
assert!(serde_json::from_value::<RenderSettings>(invalid).is_err());
}
let mut ortho = saved;
ortho["setups"]["Focus"]["camera"]["fov"] = json!(0);
assert!(serde_json::from_value::<RenderSettings>(ortho).is_err());
assert!(serde_json::to_value(CpuJob::default()).unwrap().get("lens").is_none());
}
#[test]
fn cpu_output_presentation_roundtrips_offline_without_another_exposure_authority() {
use serde_json::json;
assert!(serde_json::to_value(CpuJob::default()).unwrap().get("output").is_none());
let saved = json!({"setups":{"CPU output":{"width":64,"height":32,"exposure_ev":1.5,
"job":{"method":"cpu_raytrace","options":{"progressive":{"samples_per_pixel":7,"seed":81},
"output":{"tone_map":"aces_fitted","finishing":{"rgb_gain":[1.2,0.8,1.1],"photographic":{"grain":0.03,"seed":42},
"bloom":{"strength":0.2,"threshold":0.5,"radius":2}},"backdrop":{"mode":"radial"},"linear_exr":true}}}}}});
let settings: RenderSettings = serde_json::from_value(saved).unwrap();
let setup = &settings.setups["CPU output"];
let RenderJob::CpuRaytrace { options, .. } = setup.job.as_ref().unwrap() else { panic!("CPU job expected") };
let runtime = options.to_runtime(setup.exposure_ev).unwrap();
assert_eq!(runtime.exposure_ev, 1.5);
assert_eq!(runtime.output, options.output);
let encoded = serde_json::to_value(&settings).unwrap();
assert!(encoded["setups"]["CPU output"]["job"]["options"]["output"].get("exposure_ev").is_none());
assert_eq!(settings, serde_json::from_value::<RenderSettings>(encoded.clone()).unwrap());
for bad in [json!({"exposure_ev":1}), json!({"samples":4}), json!({"linear_exr":"yes"}), json!({"finishing":{"rgb_gain":[-1,1,1]}})] {
let mut invalid = encoded.clone();
invalid["setups"]["CPU output"]["job"]["options"]["output"] = bad;
assert!(serde_json::from_value::<RenderSettings>(invalid).is_err());
}
let wide = json!({"width":16384,"height":1,"job":{"method":"cpu_raytrace","options":{"budget":"workstation"}}});
serde_json::from_value::<RenderSetup>(wide.clone()).unwrap().validate().unwrap();
for output in [json!({"tone_map":"aces_fitted"}), json!({"linear_exr":true})] {
let mut invalid = wide.clone();
invalid["job"]["options"]["output"] = output;
assert!(
serde_json::from_value::<RenderSetup>(invalid).unwrap().validate().is_err(),
"active output must respect its existing shared envelope"
);
}
}
#[test]
fn portable_jobs_reject_unbounded_invalid_and_nonportable_inputs() {
use serde_json::json;
for setup in [
json!({"job":{}}),
json!({"job":{"method":"cpu_raytrace","options":{"primary_samples":2}}}),
json!({"exposure_ev":17,"job":{"method":"cpu_raytrace"}}),
json!({"exposure_ev":1,"job":{"method":"raster"}}),
json!({"environment_rotation":0.5,"job":{"method":"gpu_path"}}),
json!({"environment_intensity":0,"job":{"method":"cpu_raytrace"}}),
json!({"job":{"method":"cpu_raytrace","options":{"seed":-1}}}),
json!({"job":{"method":"cpu_raytrace","options":{"preset":"neutral","lights":[]}}}),
json!({"job":{"method":"cpu_raytrace","options":{"environment":{"path":"not-portable.hdr"}}}}),
json!({"job":{"method":"gpu_path","options":{"environment":{"kind":"hdr","path":"not-portable.hdr"}}}}),
json!({"job":{"method":"gpu_path","options":{"exposure_ev":0}}}),
json!({"job":{"method":"gpu_path","options":{"samples":0}}}),
json!({"job":{"method":"gpu_path","options":{"max_depth":17}}}),
json!({"job":{"method":"gpu_path","options":{"environment":{"kind":"sky","intensity":101}}}}),
json!({"job":{"method":"gpu_path","options":{"lighting":{"environment":[-1,0,0]}}}}),
json!({"camera":Camera { fov: 0.0, ..Default::default() },"job":{"method":"gpu_path","options":{"lens":{"aperture_radius_mm":1,"focus_distance_mm":10}}}}),
] {
let saved = json!({"setups":{"Bad":setup}});
assert!(serde_json::from_value::<RenderSettings>(saved.clone()).is_err(), "{saved}");
}
for (method, fields) in [
("cpu_raytrace", &["reflections", "anisotropic_faces", "surface_effects", "emissions", "dielectrics"][..]),
("gpu_path", &["textures", "clear_coats", "dielectrics"][..]),
] {
for field in fields {
let mut options = json!({});
options[*field] = json!([]);
let saved = json!({"setups":{"Bad":{"job":{"method":method,"options":options}}}});
assert!(serde_json::from_value::<RenderSettings>(saved).is_err(), "{method}.{field}");
}
}
for (field, light, maximum) in [
("lights", json!({"direction":[0,0,-1],"color":[1,1,1],"intensity":1}), 8),
(
"punctual_lights",
json!({"position_mm":[0,0,10],"color":[1,1,1],"intensity":1,"reference_distance_mm":10,"minimum_distance_mm":0.1}),
8,
),
("area_lights", json!({"center_mm":[0,0,10],"edge_u_mm":[1,0,0],"edge_v_mm":[0,-1,0],"color":[1,1,1],"intensity":1}), 4),
] {
let mut options = json!({});
options[field] = json!(vec![light; maximum + 1]);
let error = serde_json::from_value::<CpuJob>(options).unwrap_err().to_string();
assert!(error.contains(&format!("at most {maximum} saved lights")), "{error}");
}
let area = json!({"center":[0,0,10],"u":[1,0,0],"v":[0,-1,0],"radiance":[1,1,1]});
assert!(serde_json::from_value::<GpuJob>(json!({"lighting":{"area_lights":vec![area;5]}})).is_err());
let mut cpu = CpuJob { lights: Some(Vec::with_capacity(9)), ..Default::default() };
assert!(cpu.to_runtime(0.0).is_err());
cpu.lights = None;
assert!(cpu.to_runtime(f64::NAN).is_err());
let gpu = GpuJob {
environment: Some(SkyEnvironment::Sky { gradient: Default::default(), rotation_rad: f64::INFINITY, intensity: 1.0 }),
..Default::default()
};
assert!(gpu.to_runtime(0.0).is_err());
}
#[test]
fn invalid_saved_intent_is_rejected_at_deserialization() {
for patch in [
serde_json::json!({"width":0}),
serde_json::json!({"width":4097}),
serde_json::json!({"width":4096,"height":4096}),
serde_json::json!({"exposure_ev":33}),
serde_json::json!({"environment_rotation":1000001}),
serde_json::json!({"environment_intensity":-1}),
serde_json::json!({"background":[256,0,0]}),
serde_json::json!({"unknown":1}),
] {
let json = serde_json::json!({"setups":{"Studio":patch}});
assert!(serde_json::from_value::<RenderSettings>(json).is_err());
}
for name in ["", " padded", "line\nfeed"] {
assert!(RenderSettings::validate_name(name).is_err());
}
let mut settings = RenderSettings::default();
for i in 0..=MAX_RENDER_SETUPS {
settings.setups.insert(i.to_string(), RenderSetup::default());
}
assert!(serde_json::from_value::<RenderSettings>(serde_json::to_value(settings).unwrap()).is_err());
let mut setup = RenderSetup::default();
setup.camera.fov = f64::NAN;
assert!(setup.validate().is_err());
for field in ["yaw", "pitch", "roll", "distance", "fov"] {
let mut value = serde_json::to_value(RenderSetup::default()).unwrap();
value["camera"][field] = serde_json::json!(1e12);
let setup: RenderSetup = serde_json::from_value(value).unwrap();
assert!(setup.validate().is_err(), "{field}");
}
setup.camera = Camera::default();
setup.environment_intensity = f64::INFINITY;
assert!(setup.validate().is_err());
}
}
#[cfg(test)]
mod cpu_budget_tests {
use super::*;
use serde_json::json;
use solidcraft_render::job::{CpuBudget, CpuProgressiveOptions};
#[test]
fn inactive_area_tuning_roundtrips_without_leaking_into_runtime_options() {
let saved: CpuJob = serde_json::from_str(r#"{"seed":1,"area_samples":16,"area_lights":[]}"#).unwrap();
let runtime = saved.to_runtime(0.0).unwrap();
assert_eq!((saved.seed, saved.area_samples), (Some(1), Some(16)));
assert_eq!((runtime.seed, runtime.area_samples), (None, None));
let roundtrip: CpuJob = serde_json::from_value(serde_json::to_value(&saved).unwrap()).unwrap();
assert_eq!(roundtrip, saved);
let raw = solidcraft_render::job::RaytraceOptions { seed: Some(1), ..Default::default() };
assert!(raw.validate().is_err(), "runtime requests still reject tuning without active emitters");
}
#[test]
fn resource_profiles_survive_native_intent_roundtrips_without_a_host() {
let mut setup = RenderSetup {
width: 3840,
height: 2160,
job: Some(RenderJob::CpuRaytrace {
transparent_background: false,
options: Box::new(CpuJob {
budget: CpuBudget::Studio,
progressive: Some(CpuProgressiveOptions { samples_per_pixel: 128, seed: 82 }),
..Default::default()
}),
}),
..Default::default()
};
setup.validate().unwrap();
let text = serde_json::to_string(&setup).unwrap();
let reopened: RenderSetup = serde_json::from_str(&text).unwrap();
assert_eq!(setup, reopened);
let Some(RenderJob::CpuRaytrace { options, .. }) = &mut setup.job else {
panic!("CPU fixture");
};
options.budget = CpuBudget::Compact;
assert!(setup.validate().is_err());
let legacy: CpuJob = serde_json::from_str("{}").unwrap();
assert_eq!(legacy.budget, CpuBudget::Compact);
assert!(serde_json::to_value(legacy).unwrap().get("budget").is_none());
assert!(serde_json::from_str::<CpuJob>(r#"{"budget":"unlimited"}"#).is_err());
let legacy_large = RenderSetup { width: 3840, height: 2160, ..Default::default() };
assert!(legacy_large.validate().is_err(), "large intent must name an explicit CPU job profile");
}
#[test]
fn cpu_path_is_explicit_bounded_offline_intent_and_roundtrips_without_changing_legacy_jobs() {
let old = CpuJob::default();
assert!(old.path.is_none());
assert!(serde_json::to_value(&old).unwrap().get("path").is_none());
for depth in [1, 8, 16] {
let setup:RenderSetup=serde_json::from_value(json!({"width":8,"height":8,"job":{"method":"cpu_raytrace","options":{"path":{"max_depth":depth},"progressive":{"samples_per_pixel":7,"seed":9}}}})).unwrap();
setup.validate().unwrap();
let mut document = crate::Document::default();
std::sync::Arc::make_mut(&mut document.render).setups.insert("GI".into(), setup);
let bytes = serde_json::to_vec(&document).unwrap();
let reopened: crate::Document = serde_json::from_slice(&bytes).unwrap();
assert_eq!(document, reopened);
}
for raw in [
json!({"path":{"max_depth":0},"progressive":{"samples_per_pixel":7,"seed":9}}),
json!({"path":{"max_depth":17},"progressive":{"samples_per_pixel":7,"seed":9}}),
json!({"path":{"max_depth":8}}),
json!({"path":{"max_depth":8},"progressive":{"samples_per_pixel":7,"seed":9},"shadows":false}),
] {
let options: CpuJob = serde_json::from_value(raw).unwrap();
assert!(options.to_runtime(0.0).is_err());
}
assert!(serde_json::from_value::<CpuJob>(json!({"path":{"max_depth":8,"unknown":true}})).is_err());
}
}
#[cfg(test)]
#[test]
fn cpu_denoise_saved_flag_roundtrips_offline_and_keeps_false_omitted() {
use solidcraft_render::job::CpuBudget;
let mut setup = RenderSetup {
width: 16,
height: 8,
job: Some(RenderJob::CpuRaytrace { transparent_background: false, options: Box::new(CpuJob { denoise: true, ..Default::default() }) }),
..Default::default()
};
setup.validate().unwrap();
let wire = serde_json::to_value(&setup).unwrap();
assert_eq!(wire["job"]["options"]["denoise"], true);
assert_eq!(serde_json::from_value::<RenderSetup>(wire).unwrap(), setup);
let Some(RenderJob::CpuRaytrace { options, .. }) = &mut setup.job else { panic!("CPU job expected") };
assert!(options.to_runtime(1.5).unwrap().denoise);
options.denoise = false;
assert!(serde_json::to_value(&setup).unwrap()["job"]["options"].get("denoise").is_none());
let default: CpuJob = serde_json::from_value(serde_json::json!({})).unwrap();
let explicit: CpuJob = serde_json::from_value(serde_json::json!({"denoise":false})).unwrap();
assert_eq!(default, explicit);
assert!(!default.to_runtime(0.0).unwrap().denoise);
assert!(serde_json::from_value::<CpuJob>(serde_json::json!({"denoise":"true"})).is_err());
setup.width = 8193;
setup.height = 1;
let Some(RenderJob::CpuRaytrace { options, .. }) = &mut setup.job else { panic!("CPU job expected") };
options.budget = CpuBudget::Workstation;
setup.validate().unwrap();
let Some(RenderJob::CpuRaytrace { options, .. }) = &mut setup.job else { panic!("CPU job expected") };
options.denoise = true;
assert!(setup.validate().unwrap_err().to_string().contains("CPU denoising"));
}
#[cfg(test)]
#[test]
fn composed_cpu_path_preserves_saved_optics_alpha_filter_lens_and_master_intent() {
use crate::render_optics::{OpticalMaterial, SavedOptics};
use crate::render_surface::RenderBodyTarget;
use solidcraft_render::job::{CpuPathOptions, CpuProgressiveOptions, OutputOptions, ThinLens};
let mut setup = RenderSetup {
camera: Camera { fov: 0.6, distance: 123.0, ..Default::default() },
width: 8,
height: 8,
job: Some(RenderJob::CpuRaytrace {
transparent_background: true,
options: Box::new(CpuJob {
denoise: true,
path: Some(CpuPathOptions { max_depth: 3 }),
progressive: Some(CpuProgressiveOptions { samples_per_pixel: 3, seed: 81 }),
lens: Some(ThinLens { aperture_radius_mm: 1.0, focus_distance_mm: 123.0 }),
output: Some(Box::new(OutputOptions { linear_exr: true, ..Default::default() })),
..Default::default()
}),
}),
..Default::default()
};
setup.validate().unwrap();
setup
.optics
.set(
SavedOptics {
target: RenderBodyTarget { definition: "Glass".into(), feature: 1, component: 0, occurrence_path: Vec::new() },
optics: OpticalMaterial::default(),
},
false,
)
.unwrap();
let before = setup.clone();
setup.validate().unwrap();
assert_eq!(setup, before, "validation must not lower or rewrite authored optics");
let Some(RenderJob::CpuRaytrace { options, .. }) = &mut setup.job else { panic!("CPU fixture") };
options.path = None;
setup.validate().unwrap();
assert!(matches!(&setup.job, Some(RenderJob::CpuRaytrace { transparent_background:true, options })
if options.denoise && options.output.as_ref().unwrap().linear_exr && options.lens.is_some()));
}
#[cfg(test)]
#[test]
fn gpu_hard_directional_intent_roundtrips_and_hostile_lists_refuse_at_document_load() {
use serde_json::json;
let light = json!({"direction":[0.0,0.0,2.0],"color":[0.25,0.5,1.0],"intensity":0.0});
let settings = json!({"setups":{"Lights":{"job":{"method":"gpu_path","options":{"lighting":{"directional_lights":vec![light.clone();8]}}}}}});
let saved: RenderSettings = serde_json::from_value(settings.clone()).unwrap();
let doc = crate::Document { render: std::sync::Arc::new(saved.clone()), ..Default::default() };
assert_eq!(crate::Document::from_json(&doc.to_json()).unwrap(), doc);
let encoded = serde_json::to_value(&saved).unwrap();
assert_eq!(encoded["setups"]["Lights"]["job"]["options"]["lighting"]["directional_lights"], json!(vec![light.clone(); 8]));
for list in [
json!(vec![light.clone(); 9]),
json!([{"direction":[0,0,0],"color":[1,1,1],"intensity":1}]),
json!([{"direction":[0,0,1],"color":[1,1,1],"intensity":65}]),
] {
let mut bad = settings.clone();
bad["setups"]["Lights"]["job"]["options"]["lighting"]["directional_lights"] = list;
assert!(serde_json::from_value::<RenderSettings>(bad).is_err());
}
let mut over_combined = settings;
over_combined["setups"]["Lights"]["job"]["options"]["lighting"]["sun"] =
json!({"direction":[0,0,1],"angular_radius_rad":0.02,"radiance":[1,1,1]});
assert!(serde_json::from_value::<RenderSettings>(over_combined.clone()).is_err());
let mut document = serde_json::to_value(crate::Document::default()).unwrap();
document["render"] = over_combined;
assert!(crate::Document::from_json(&serde_json::to_string(&document).unwrap()).is_err());
let old: RenderSettings = serde_json::from_value(json!({"setups":{"Old":{"job":{"method":"gpu_path","options":{}}}}})).unwrap();
let Some(RenderJob::GpuPath { options, .. }) = &old.setups["Old"].job else { panic!("gpu job") };
assert!(options.lighting.is_none());
}
#[cfg(test)]
#[test]
fn saved_cpu_aging_is_optional_bounded_and_preserves_stable_targets_without_runtime_ordinals() {
use crate::render_aging::SavedAgingStack;
use crate::render_surface::RenderBodyTarget;
use solidcraft_render::job::aging::{AgingKind, AgingLayer};
let old = CpuJob::default();
assert!(serde_json::to_value(&old).unwrap().get("aging").is_none());
let mut layers = SavedAgingStack::default();
layers.push(AgingLayer::preset(AgingKind::Dust)).unwrap();
let target = RenderBodyTarget { definition: "Aged panel".into(), feature: 19, component: 0, occurrence_path: Vec::new() };
layers.get_mut(0).unwrap().target = Some(target.clone());
let job = CpuJob { aging: layers.clone(), progressive: Some(Default::default()), denoise: true, ..Default::default() };
job.validate(0.5).unwrap();
assert!(job.to_runtime(0.5).unwrap_err().to_string().contains("stable occurrence"));
let setup = RenderSetup {
width: 8,
height: 8,
exposure_ev: 0.5,
job: Some(RenderJob::CpuRaytrace { transparent_background: true, options: Box::new(job) }),
..Default::default()
};
setup.validate().unwrap();
let wire = serde_json::to_value(&setup).unwrap();
assert_eq!(wire["job"]["options"]["aging"][0]["target"]["definition"], "Aged panel");
assert!(wire["job"]["options"]["aging"][0]["target"].get("body_index").is_none());
assert_eq!(serde_json::from_value::<RenderSetup>(wire.clone()).unwrap(), setup);
let mut legacy = wire.clone();
legacy["job"]["options"]["aging"][0]["target"] = serde_json::json!({"body_index":0,"body_name":"Aged panel"});
assert!(serde_json::from_value::<RenderSetup>(legacy).unwrap_err().to_string().contains("explicit rebinding"));
let mut nine = wire;
nine["job"]["options"]["aging"] = serde_json::json!(vec![serde_json::json!({}); 9]);
assert!(serde_json::from_value::<RenderSetup>(nine).is_err());
layers.get_mut(0).unwrap().target = None;
let runtime = CpuJob { aging: layers, ..Default::default() }.to_runtime(0.5).unwrap();
assert!(runtime.aging.unwrap().active());
}
#[cfg(test)]
mod cpu_adaptive_saved_tests {
use super::*;
use serde_json::json;
use solidcraft_render::job::{CpuBudget, CpuProgressiveOptions};
#[test]
fn saved_cpu_adaptive_intent_roundtrips_offline_and_pays_pilots_inside_the_existing_profile() {
let setup: RenderSetup = serde_json::from_value(json!({"width":128,"height":64,
"job":{"method":"cpu_raytrace","transparent_background":true,"options":{
"progressive":{"samples_per_pixel":48,"seed":81},"adaptive":{"pilot_samples":16,"min_samples":16},
"denoise":true,"path":{"max_depth":3},"output":{"linear_exr":true}}}}))
.unwrap();
setup.validate().unwrap();
let value = serde_json::to_value(&setup).unwrap();
assert_eq!(serde_json::from_value::<RenderSetup>(value.clone()).unwrap(), setup);
let Some(RenderJob::CpuRaytrace { options, .. }) = setup.job.as_ref() else { panic!("CPU job expected") };
let runtime = options.to_runtime(0.0).unwrap();
assert_eq!(runtime.adaptive.as_deref().copied(), options.adaptive);
assert_eq!(runtime.preview_target().unwrap(), 64);
assert_eq!(runtime.camera_sampling().unwrap(), Some(CpuProgressiveOptions { samples_per_pixel: 64, seed: 81 }));
let mut too_large = setup.clone();
too_large.width = 1024;
too_large.height = 1024;
assert!(too_large.validate().is_err(), "64 total passes exceed Compact's existing camera-sample bound");
let mut cap = value.clone();
cap["job"]["options"]["progressive"]["samples_per_pixel"] = json!(64);
assert!(
serde_json::from_value::<RenderSetup>(cap).unwrap().validate().is_err(),
"16 pilots cannot be hidden outside Compact's 64-sample cap"
);
for (budget, maximum) in [(CpuBudget::Compact, 64), (CpuBudget::Studio, 1024), (CpuBudget::Workstation, 4096)] {
let mut runtime = runtime.clone();
runtime.budget = budget;
runtime.progressive = Some(CpuProgressiveOptions { samples_per_pixel: maximum - 16, seed: 81 });
assert_eq!(runtime.preview_target().unwrap(), maximum);
runtime.progressive.as_mut().unwrap().samples_per_pixel += 1;
assert!(runtime.validate().is_err(), "{budget:?} must include the pilot stage in its unchanged cap");
}
let mut fixed = value.clone();
fixed["job"]["options"].as_object_mut().unwrap().remove("progressive");
assert!(serde_json::from_value::<RenderSetup>(fixed).unwrap().validate().is_err());
let mut hostile = value;
hostile["job"]["options"]["adaptive"]["certified_convergence"] = json!(true);
assert!(serde_json::from_value::<RenderSetup>(hostile).is_err());
let old = serde_json::to_value(CpuJob::default()).unwrap();
assert!(old.get("adaptive").is_none(), "default-absent saved jobs keep their prior schema bytes");
}
}
#[cfg(test)]
mod saved_coat_tests {
use super::*;
use crate::{
Document,
render_coat::{CoatMaterial, SavedCoat},
render_surface::RenderBodyTarget,
};
use serde_json::{Value, json};
use std::sync::Arc;
fn target(feature: u64) -> RenderBodyTarget {
RenderBodyTarget { definition: format!("Coated{feature}"), feature, component: 0, occurrence_path: vec![] }
}
fn document(gpu: bool) -> Document {
let mut doc = Document::default();
let job = if gpu {
RenderJob::GpuPath { transparent_background: false, options: Default::default() }
} else {
RenderJob::CpuRaytrace { transparent_background: false, options: Default::default() }
};
Arc::make_mut(&mut doc.render).setups.insert("Coated".into(), RenderSetup { width: 8, height: 8, job: Some(job), ..Default::default() });
doc
}
#[test]
fn saved_coat_document_roundtrip_preserves_every_number_and_old_omission_for_both_methods() {
for gpu in [false, true] {
let mut doc = document(gpu);
let old = doc.to_json();
let old_value: Value = serde_json::from_str(&old).unwrap();
assert!(old_value["render"]["setups"]["Coated"].get("coats").is_none());
assert_eq!(Document::from_json(&old).unwrap().to_json(), old);
let coat = CoatMaterial { weight: -0.0, roughness: 0.22, ior: 1.74 };
Arc::make_mut(&mut doc.render).setups.get_mut("Coated").unwrap().coats.set(SavedCoat { target: target(1), coat }, false).unwrap();
let encoded = doc.to_json();
let loaded = Document::from_json(&encoded).unwrap();
assert_eq!(loaded.render, doc.render);
let saved = loaded.render.setups["Coated"].coats.iter().next().unwrap();
assert_eq!(saved.coat, coat);
assert_eq!(saved.coat.weight.to_bits(), (-0.0_f64).to_bits());
let wire = serde_json::to_value(saved).unwrap();
assert!(wire.get("body_index").is_none() && wire.get("body_name").is_none());
assert!(wire["target"].get("feature").is_some());
let setup = Arc::make_mut(&mut doc.render).setups.get_mut("Coated").unwrap();
let changed = SavedCoat { target: target(1), coat: CoatMaterial { weight: 0.0, ..coat } };
assert!(setup.coats.set(changed.clone(), false).is_err(), "authored signed zero is not silently replaced");
setup.coats.set(changed, true).unwrap();
assert_eq!(setup.coats.iter().next().unwrap().coat.weight.to_bits(), 0.0_f64.to_bits());
assert!(setup.coats.remove(&target(1)));
assert_eq!(doc.to_json(), old, "removing the only coat restores exact legacy document bytes");
}
}
#[test]
fn malformed_saved_coats_refuse_through_the_full_document_loader() {
let mut doc = document(false);
Arc::make_mut(&mut doc.render)
.setups
.get_mut("Coated")
.unwrap()
.coats
.set(SavedCoat { target: target(1), coat: Default::default() }, false)
.unwrap();
let base: Value = serde_json::from_str(&doc.to_json()).unwrap();
for (key, value) in
[("weight", json!(-0.01)), ("weight", json!(1.01)), ("roughness", json!(0.02)), ("ior", json!(3.01)), ("unknown", json!(true))]
{
let mut bad = base.clone();
bad["render"]["setups"]["Coated"]["coats"][0]["coat"][key] = value;
assert!(Document::from_json(&bad.to_string()).is_err(), "invalid coat {key}");
}
let mut duplicate = base.clone();
let row = duplicate["render"]["setups"]["Coated"]["coats"][0].clone();
duplicate["render"]["setups"]["Coated"]["coats"] = json!([row, row]);
assert!(Document::from_json(&duplicate.to_string()).is_err());
for key in ["body_index", "runtime_path"] {
let mut bad = base.clone();
bad["render"]["setups"]["Coated"]["coats"][0][key] = json!(0);
assert!(Document::from_json(&bad.to_string()).is_err());
}
let mut too_many = base;
too_many["render"]["setups"]["Coated"]["coats"] =
json!((1..=65).map(|feature| SavedCoat { target: target(feature), coat: Default::default() }).collect::<Vec<_>>());
assert!(Document::from_json(&too_many.to_string()).is_err());
}
#[test]
fn saved_coat_uses_existing_sixty_four_target_bound_and_rejects_glass_even_at_zero_weight() {
use crate::render_optics::{OpticalMaterial, SavedOptics};
for gpu in [false, true] {
let mut doc = document(gpu);
let setup = Arc::make_mut(&mut doc.render).setups.get_mut("Coated").unwrap();
for feature in 1..=64 {
setup.coats.set(SavedCoat { target: target(feature), coat: CoatMaterial { weight: 0.0, ..Default::default() } }, false).unwrap();
}
setup.validate().unwrap();
assert_eq!(setup.coats.len(), 64);
let before = setup.coats.clone();
assert!(setup.coats.set(SavedCoat { target: target(65), coat: Default::default() }, false).is_err());
assert_eq!(setup.coats, before);
setup.optics.set(SavedOptics { target: target(1), optics: OpticalMaterial::default() }, false).unwrap();
assert!(setup.validate().unwrap_err().to_string().contains("cannot share"));
setup.optics.remove(&target(1));
setup.job = Some(RenderJob::Raster { transparent_background: false });
assert!(setup.validate().unwrap_err().to_string().contains("raytrace"));
assert_eq!(setup.coats, before, "unsupported method retains all authored rows");
}
}
}
#[cfg(test)]
mod cpu_celestial_saved_tests {
use super::*;
use serde_json::json;
#[test]
fn saved_cpu_finite_sun_and_sky_roundtrip_exactly_and_require_explicit_path() {
let value = json!({"width":16,"height":12,"job":{"method":"cpu_raytrace","transparent_background":true,"options":{
"path":{"max_depth":4},"progressive":{"samples_per_pixel":32,"seed":81},"adaptive":{"pilot_samples":16,"min_samples":16},
"sun":{"direction":[0.2,-0.3,0.9],"angular_radius_rad":0.02,"radiance":[301.25,202.5,103.75]},
"sky":{"kind":"sky","gradient":{"zenith":[0.25,0.5,1.0],"horizon":[0.75,0.5,0.25],"ground":[0.125,0.25,0.5]},"rotation_rad":0.731,"intensity":75},
"denoise":true,"output":{"linear_exr":true},"lights":[]}}});
let setup: RenderSetup = serde_json::from_value(value.clone()).unwrap();
setup.validate().unwrap();
let wire = serde_json::to_value(&setup).unwrap();
assert_eq!(serde_json::from_value::<RenderSetup>(wire.clone()).unwrap(), setup);
let Some(RenderJob::CpuRaytrace { options, .. }) = &setup.job else { panic!("CPU expected") };
let runtime = options.to_runtime(0.0).unwrap();
assert_eq!(runtime.sun.as_deref().copied(), options.sun);
assert_eq!(runtime.sky.as_deref().unwrap().intensity, 75.0);
assert_eq!(runtime.sky.as_deref().unwrap().rotation_rad, 0.731);
for (field, replacement) in [
("path", serde_json::Value::Null),
("sun", json!({"direction":[0,0,1],"angular_radius_rad":0,"radiance":[1,1,1]})),
("environment", json!({"color":[1,1,1],"intensity":1})),
] {
let mut invalid = wire.clone();
invalid["job"]["options"][field] = replacement;
assert!(serde_json::from_value::<RenderSetup>(invalid).unwrap().validate().is_err(), "{field} must not be silently replaced");
}
for (field, value) in [("intensity", json!(100.001)), ("rotation_rad", json!(1e6 + 1.0))] {
let mut invalid = wire.clone();
invalid["job"]["options"]["sky"][field] = value;
assert!(serde_json::from_value::<RenderSetup>(invalid).unwrap().validate().is_err());
}
let defaults = serde_json::to_value(CpuJob::default()).unwrap();
assert!(defaults.get("sun").is_none() && defaults.get("sky").is_none());
}
}