SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Bounded texture admission, independent of documents, files, schedulers and GPU handles.
//! This utility does not advertise texture/PBR support or define a persistent pack schema.
use image::{ImageDecoder, ImageFormat, ImageReader, Limits};
use serde::{Deserialize, Serialize};
use std::{io::Cursor, sync::Arc};
pub mod normalization;
pub(crate) mod png_metadata;
pub const MAX_TEXTURE_BYTES: usize = 16 * 1024 * 1024;
pub const MAX_TEXTURE_EDGE: u32 = 2048;
pub(crate) const MAX_CODEC_BYTES: u64 = 64 * 1024 * 1024;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MapRole {
BaseColor,
NormalOpenGl,
Roughness,
Metallic,
AmbientOcclusion,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Interpretation {
Srgb,
Data,
}
impl MapRole {
pub fn interpretation(self) -> Interpretation {
if self == Self::BaseColor { Interpretation::Srgb } else { Interpretation::Data }
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TextureError(pub String);
impl std::fmt::Display for TextureError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.0)
}
}
impl std::error::Error for TextureError {}
type Result<T> = std::result::Result<T, TextureError>;
fn invalid(message: impl Into<String>) -> TextureError {
TextureError(message.into())
}
#[derive(Clone, Debug, Serialize)]
pub struct TextureInfo {
pub width: u32,
pub height: u32,
pub encoded_bytes: usize,
pub rgba_bytes: u64,
pub role: MapRole,
pub interpretation: Interpretation,
}
/// An explicit base-color role means normalized sRGB samples. Reject conflicting
/// encoded declarations; data roles preserve their numerical channels unchanged.
pub fn validate_color_declarations(bytes: &[u8], role: MapRole) -> Result<()> {
if role == MapRole::BaseColor && bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
png_metadata::validate_srgb_declarations(bytes)?;
}
Ok(())
}
/// Header-admitted source. Full decoding must succeed before publishing pixels.
#[derive(Clone)]
pub struct TextureSource {
bytes: Arc<Vec<u8>>,
format: ImageFormat,
info: TextureInfo,
}
fn reader(bytes: &[u8], format: ImageFormat) -> ImageReader<Cursor<&[u8]>> {
let mut reader = ImageReader::with_format(Cursor::new(bytes), format);
let mut limits = Limits::default();
limits.max_image_width = Some(MAX_TEXTURE_EDGE);
limits.max_image_height = Some(MAX_TEXTURE_EDGE);
limits.max_alloc = Some(MAX_CODEC_BYTES);
reader.limits(limits);
reader
}
fn guarded<T>(work: impl FnOnce() -> Result<T>) -> Result<T> {
std::panic::catch_unwind(std::panic::AssertUnwindSafe(work)).map_err(|_| invalid("texture decoder failed"))?
}
fn admitted_format(bytes: &[u8], capacity: usize) -> Result<ImageFormat> {
if bytes.is_empty() || bytes.len() > MAX_TEXTURE_BYTES || capacity > MAX_TEXTURE_BYTES {
return Err(invalid("texture input must contain at most 16 MiB"));
}
let format = image::guess_format(bytes).map_err(|_| invalid("texture must be PNG or JPEG"))?;
if !matches!(format, ImageFormat::Png | ImageFormat::Jpeg) {
return Err(invalid("texture must be PNG or JPEG; HDR uses the Radiance input utility"));
}
// Whole-image codecs may return pixels before noticing a missing trailer. This
// marker check rejects that truncation; it is not a general container validator.
let complete = match format {
ImageFormat::Png => bytes.ends_with(b"\x00\x00\x00\x00IEND\xae\x42\x60\x82"),
ImageFormat::Jpeg => bytes.ends_with(b"\xff\xd9"),
_ => false,
};
if !complete {
return Err(invalid("texture is missing its final terminator"));
}
Ok(format)
}
impl TextureSource {
#[cfg(test)]
pub(crate) fn shares_encoded_storage(&self, other: &Self) -> bool {
Arc::ptr_eq(&self.bytes, &other.bytes)
}
pub fn new(bytes: Vec<u8>, role: MapRole) -> Result<Self> {
let format = admitted_format(&bytes, bytes.capacity())?;
if format == ImageFormat::Png {
png_metadata::validate(&bytes)?;
}
let (width, height) = guarded(|| {
let mut decoder = reader(&bytes, format).into_decoder().map_err(|e| invalid(e.to_string()))?;
if !matches!(decoder.color_type(), image::ColorType::L8 | image::ColorType::La8 | image::ColorType::Rgb8 | image::ColorType::Rgba8) {
return Err(invalid("only 8-bit texture channels are supported"));
}
if decoder.icc_profile().map_err(|e| invalid(e.to_string()))?.is_some() {
return Err(invalid("embedded ICC profiles need explicit color conversion before admission"));
}
if decoder.orientation().map_err(|e| invalid(e.to_string()))? != image::metadata::Orientation::NoTransforms {
return Err(invalid("texture orientation must be normalized before admission"));
}
Ok(decoder.dimensions())
})?;
if width == 0 || height == 0 || width > MAX_TEXTURE_EDGE || height > MAX_TEXTURE_EDGE {
return Err(invalid("texture dimensions exceed 2048x2048"));
}
let rgba_bytes = u64::from(width) * u64::from(height) * 4;
let info = TextureInfo { width, height, encoded_bytes: bytes.len(), rgba_bytes, role, interpretation: role.interpretation() };
Ok(Self { bytes: Arc::new(bytes), format, info })
}
/// Admit a portable source with strict PNG metadata and color declarations
/// before opening its codec. Legacy runtime inputs keep `new`'s admission.
pub fn new_portable(bytes: Vec<u8>, role: MapRole) -> Result<Self> {
if admitted_format(&bytes, bytes.capacity())? == ImageFormat::Png {
png_metadata::validate(&bytes)?;
validate_color_declarations(&bytes, role)?;
}
Self::new(bytes, role)
}
pub fn info(&self) -> &TextureInfo {
&self.info
}
/// Complete static-source metadata admission before portable publication.
/// This bounded scan belongs on the caller's existing import worker. It does
/// not replace pixel decoding or the cooperative image worker's own checks.
pub fn validate_static_source(&self) -> Result<()> {
if self.format == ImageFormat::Png {
let mut metadata = png_metadata::PngMetadata::new(true, true).with_role(self.info.role);
while !metadata.step(&self.bytes)? {}
}
Ok(())
}
/// Share admitted encoded ownership with the cooperative native row worker.
#[cfg(feature = "raytrace-cpu")]
pub(crate) fn png_encoded(&self) -> Result<Arc<Vec<u8>>> {
if self.format != ImageFormat::Png || self.bytes.get(24).copied() != Some(8) || self.bytes.get(28).copied() != Some(0) {
return Err(invalid("CPU row preparation supports noninterlaced 8-bit PNG only"));
}
Ok(self.bytes.clone())
}
#[cfg(all(test, feature = "raytrace-cpu"))]
pub(crate) fn encoded_weak(&self) -> std::sync::Weak<Vec<u8>> {
Arc::downgrade(&self.bytes)
}
/// Bounded whole-image codec work, intended for a caller-owned worker. Cancellation is
/// checked at the codec boundary, not during PNG/JPEG decoding. No partial image escapes.
pub fn decode(&self, cancelled: impl Fn() -> bool) -> Result<DecodedTexture> {
if cancelled() {
return Err(invalid("texture decoding cancelled"));
}
let image = guarded(|| reader(&self.bytes, self.format).decode().map_err(|e| invalid(e.to_string())))?;
if cancelled() {
return Err(invalid("texture decoding cancelled"));
}
let pixels = guarded(|| Ok(image.into_rgba8().into_raw()))?;
if cancelled() {
return Err(invalid("texture decoding cancelled"));
}
if pixels.len() as u64 != self.info.rgba_bytes {
return Err(invalid("decoded texture dimensions changed"));
}
Ok(DecodedTexture { info: self.info.clone(), pixels })
}
}
/// Completed pixels retain encoded channel values. sRGB conversion, normal basis handling
/// and sampling belong to the eventual renderer adapter, not this input utility.
pub struct DecodedTexture {
info: TextureInfo,
pixels: Vec<u8>,
}
impl DecodedTexture {
pub fn info(&self) -> &TextureInfo {
&self.info
}
pub fn rgba(&self) -> &[u8] {
&self.pixels
}
}
#[cfg(test)]
mod tests;