Skip to main content

qualia_core_db/render/
portal_load_textures.rs

1//! PNG/KTX2 ingest for QualiaPortal `load_10d` materials.
2//!
3//! Texture payloads stay outside `.10d` (HMC/deps). This helper turns caller-
4//! supplied encoded bytes into GPU RGBA, or skips when KTX2/BasisU transcode
5//! is refused. Decode budgets are caller-owned and separate from the 42 MiB
6//! Prolog/`SlgArena` sentinel.
7
8use crate::container_10d::MaterialRecord;
9use crate::render::asset_package::HmcTextureResource;
10use crate::render::texture_decode::{
11    decode_hmc_texture_rgba8_into, inspect_hmc_texture_plan, DecodedTextureInfo, TextureColorSpace,
12    TextureDecodeError, TextureDecodeLimits, TextureDecodePlan,
13};
14use crate::render::texture_ingestion::{
15    validate_image_signature, JPEG_SIGNATURE, PNG_SIGNATURE,
16};
17use crate::render::texture_ktx2::{Ktx2Document, KTX2_IDENTIFIER};
18use sha2::{Digest, Sha256};
19
20/// Portal image decode ceiling. Independent of the 42 MiB Prolog sentinel.
21pub const PORTAL_TEXTURE_DECODE_LIMITS: TextureDecodeLimits = TextureDecodeLimits {
22    max_encoded_bytes: 4 * 1024 * 1024,
23    max_width: 4096,
24    max_height: 4096,
25    max_decoded_bytes: 4 * 1024 * 1024,
26};
27
28/// Content-addressed encoded texture ready to bind onto a MAT3/MAT4 slot.
29#[derive(Clone, Debug, PartialEq, Eq)]
30pub struct PackedPbrTexture {
31    pub digest: [u8; 32],
32    pub mime_type: &'static str,
33    pub bytes: Vec<u8>,
34}
35
36/// Optional albedo + metallic-roughness PNG/KTX2 set for `compile_10d_pbr`.
37#[derive(Clone, Debug, Default, PartialEq, Eq)]
38pub struct PackedPbrSet {
39    pub albedo: Option<PackedPbrTexture>,
40    pub metallic_roughness: Option<PackedPbrTexture>,
41}
42
43impl PackedPbrSet {
44    /// Copy packed digests onto unbound (all-zero) material slots.
45    pub fn apply_to(&self, material: &mut MaterialRecord) {
46        if let Some(albedo) = &self.albedo {
47            if material.base_color_texture == [0; 32] {
48                material.base_color_texture = albedo.digest;
49            }
50        }
51        if let Some(metallic_roughness) = &self.metallic_roughness {
52            if material.metallic_roughness_texture == [0; 32] {
53                material.metallic_roughness_texture = metallic_roughness.digest;
54            }
55        }
56    }
57}
58
59/// Decoded tightly packed RGBA8 ready for GPU upload.
60#[derive(Clone, Debug, PartialEq, Eq)]
61pub struct DecodedPortalRgba8 {
62    pub digest: [u8; 32],
63    pub width: u32,
64    pub height: u32,
65    pub rgba8: Vec<u8>,
66    pub color_space: TextureColorSpace,
67}
68
69/// Ingest outcome. Transcode-only KTX2/BasisU is skipped, never panicked.
70#[derive(Clone, Debug, PartialEq, Eq)]
71pub enum PortalTextureIngest {
72    Rgba8(DecodedPortalRgba8),
73    SkippedTranscode,
74}
75
76#[derive(Clone, Debug, PartialEq, Eq)]
77pub enum PortalTextureError {
78    Empty,
79    UnknownFormat,
80    Signature,
81    Decode(TextureDecodeError),
82}
83
84impl std::fmt::Display for PortalTextureError {
85    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
86        match self {
87            Self::Empty => write!(f, "portal texture: empty payload"),
88            Self::UnknownFormat => write!(f, "portal texture: unknown image magic"),
89            Self::Signature => write!(f, "portal texture: MIME/magic mismatch"),
90            Self::Decode(error) => write!(f, "portal texture: {error}"),
91        }
92    }
93}
94
95impl std::error::Error for PortalTextureError {}
96
97impl From<TextureDecodeError> for PortalTextureError {
98    fn from(value: TextureDecodeError) -> Self {
99        Self::Decode(value)
100    }
101}
102
103/// Identify PNG / JPEG / KTX2 from the file magic. No new container magics.
104pub fn detect_texture_mime(bytes: &[u8]) -> Option<&'static str> {
105    if bytes.len() >= 8 && bytes[..8] == PNG_SIGNATURE {
106        Some("image/png")
107    } else if bytes.len() >= 12 && bytes[..12] == KTX2_IDENTIFIER {
108        Some("image/ktx2")
109    } else if bytes.len() >= 3 && bytes[..3] == JPEG_SIGNATURE {
110        Some("image/jpeg")
111    } else {
112        None
113    }
114}
115
116fn pack_one(bytes: &[u8]) -> Result<PackedPbrTexture, PortalTextureError> {
117    if bytes.is_empty() {
118        return Err(PortalTextureError::Empty);
119    }
120    let mime_type = detect_texture_mime(bytes).ok_or(PortalTextureError::UnknownFormat)?;
121    validate_image_signature(mime_type, bytes).map_err(|_| PortalTextureError::Signature)?;
122    Ok(PackedPbrTexture {
123        digest: Sha256::digest(bytes).into(),
124        mime_type,
125        bytes: bytes.to_vec(),
126    })
127}
128
129/// Hash and signature-check encoded PBR maps. Payloads stay encoded (HMC-shaped).
130pub fn pack_pbr_set(
131    albedo: Option<&[u8]>,
132    metallic_roughness: Option<&[u8]>,
133) -> Result<PackedPbrSet, PortalTextureError> {
134    Ok(PackedPbrSet {
135        albedo: albedo.map(pack_one).transpose()?,
136        metallic_roughness: metallic_roughness.map(pack_one).transpose()?,
137    })
138}
139
140/// Decode PNG/JPEG/uncompressed KTX2 to RGBA8. BasisU/block KTX2 is skipped.
141pub fn ingest_portal_texture(
142    mime: Option<&str>,
143    bytes: &[u8],
144) -> Result<PortalTextureIngest, PortalTextureError> {
145    if bytes.is_empty() {
146        return Err(PortalTextureError::Empty);
147    }
148    let mime_type = match mime {
149        Some(declared) if !declared.is_empty() => declared,
150        _ => detect_texture_mime(bytes).ok_or(PortalTextureError::UnknownFormat)?,
151    };
152    validate_image_signature(mime_type, bytes).map_err(|_| PortalTextureError::Signature)?;
153    let digest: [u8; 32] = Sha256::digest(bytes).into();
154    let resource = HmcTextureResource {
155        digest,
156        mime_type,
157        bytes,
158    };
159
160    if mime_type
161        .split(';')
162        .next()
163        .map(str::trim)
164        .is_some_and(|m| m.eq_ignore_ascii_case("image/ktx2"))
165    {
166        // Structural parse first so a corrupt KTX2 is a decode error, not a skip.
167        let _document = Ktx2Document::parse(bytes)
168            .map_err(|_| PortalTextureError::Decode(TextureDecodeError::InvalidImage))?;
169    }
170
171    match inspect_hmc_texture_plan(&resource, PORTAL_TEXTURE_DECODE_LIMITS)? {
172        TextureDecodePlan::RequiresTranscode(_) => Ok(PortalTextureIngest::SkippedTranscode),
173        TextureDecodePlan::DecodeRgba8 {
174            info,
175            scratch_bytes,
176        } => Ok(PortalTextureIngest::Rgba8(decode_rgba8(
177            &resource,
178            digest,
179            info,
180            scratch_bytes,
181        )?)),
182    }
183}
184
185fn decode_rgba8(
186    resource: &HmcTextureResource<'_>,
187    digest: [u8; 32],
188    info: DecodedTextureInfo,
189    scratch_bytes: usize,
190) -> Result<DecodedPortalRgba8, PortalTextureError> {
191    let mut output = vec![0; info.rgba8_bytes];
192    let mut scratch = vec![0; scratch_bytes];
193    let decoded = decode_hmc_texture_rgba8_into(
194        resource,
195        PORTAL_TEXTURE_DECODE_LIMITS,
196        &mut output,
197        &mut scratch,
198    )?;
199    Ok(DecodedPortalRgba8 {
200        digest,
201        width: decoded.width,
202        height: decoded.height,
203        rgba8: output,
204        color_space: decoded.color_space,
205    })
206}
207
208/// True when `digest` occupies any MAT texture slot.
209pub fn material_references_digest(material: &MaterialRecord, digest: [u8; 32]) -> bool {
210    digest != [0; 32]
211        && (material.base_color_texture == digest
212            || material.normal_texture == digest
213            || material.metallic_roughness_texture == digest
214            || material.occlusion_texture == digest
215            || material.emissive_texture == digest
216            || material.stylized_ramp_texture == digest)
217}
218
219pub use crate::render::material_compile::compile_10d_pbr;
220
221#[cfg(feature = "gpu-runtime")]
222fn gpu_color_space(
223    decoded: TextureColorSpace,
224    fallback: crate::render::gpu::TextureColorSpace,
225) -> crate::render::gpu::TextureColorSpace {
226    match decoded {
227        TextureColorSpace::Linear => crate::render::gpu::TextureColorSpace::Linear,
228        TextureColorSpace::Srgb => crate::render::gpu::TextureColorSpace::Srgb,
229        TextureColorSpace::Unknown => fallback,
230    }
231}
232
233#[cfg(feature = "gpu-runtime")]
234fn slot_for_digest(
235    materials: &[MaterialRecord],
236    digest: [u8; 32],
237) -> (
238    crate::render::gpu::TextureColorSpace,
239    crate::render::gpu::TextureMipSemantic,
240) {
241    use crate::container_10d::OpacityMode;
242    use crate::render::gpu::{TextureColorSpace, TextureMipSemantic};
243    for material in materials {
244        if material.base_color_texture == digest {
245            let mip = if material.opacity_mode == OpacityMode::Mask {
246                TextureMipSemantic::alpha_mask(material.alpha_cutoff)
247                    .unwrap_or(TextureMipSemantic::Color)
248            } else {
249                TextureMipSemantic::Color
250            };
251            return (TextureColorSpace::Srgb, mip);
252        }
253        if material.emissive_texture == digest || material.stylized_ramp_texture == digest {
254            return (TextureColorSpace::Srgb, TextureMipSemantic::Color);
255        }
256        if material.normal_texture == digest {
257            return (TextureColorSpace::Linear, TextureMipSemantic::Normal);
258        }
259        if material.metallic_roughness_texture == digest || material.occlusion_texture == digest
260        {
261            return (TextureColorSpace::Linear, TextureMipSemantic::LinearData);
262        }
263    }
264    (TextureColorSpace::Srgb, TextureMipSemantic::Color)
265}
266
267/// Upload decoded RGBA into the TextureResidency ledger (not the Prolog sentinel).
268#[cfg(feature = "gpu-runtime")]
269pub fn upload_portal_texture_rgba8(
270    gpu: &mut crate::render::gpu::PortalGpu,
271    materials: &[MaterialRecord],
272    decoded: &DecodedPortalRgba8,
273) -> Result<(), String> {
274    let (fallback_space, semantic) = slot_for_digest(materials, decoded.digest);
275    gpu.upload_resident_texture_rgba8_with_mips(
276        decoded.digest,
277        gpu_color_space(decoded.color_space, fallback_space),
278        semantic,
279        decoded.width,
280        decoded.height,
281        &decoded.rgba8,
282    )
283    .map_err(|error| format!("portal texture upload: {error}"))
284}