Skip to main content

qualia_core_db/render/
texture_decode.rs

1//! Bounded cold-path image decoding for renderer resources.
2//!
3//! Decoders write into caller-owned RGBA8 and scratch buffers. Image payloads remain external to
4//! the semantic arena; this module only enforces per-image decode limits before GPU admission.
5
6use super::asset_package::HmcTextureResource;
7use super::texture_ktx2::{Ktx2ColorSpace, Ktx2TranscodeSource};
8
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub struct TextureDecodeLimits {
11    pub max_encoded_bytes: usize,
12    pub max_width: u32,
13    pub max_height: u32,
14    pub max_decoded_bytes: usize,
15}
16
17impl Default for TextureDecodeLimits {
18    fn default() -> Self {
19        Self {
20            max_encoded_bytes: 64 * 1024 * 1024,
21            max_width: 16_384,
22            max_height: 16_384,
23            max_decoded_bytes: 256 * 1024 * 1024,
24        }
25    }
26}
27
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub struct DecodedTextureInfo {
30    pub width: u32,
31    pub height: u32,
32    pub rgba8_bytes: usize,
33    /// PNG/JPEG metadata is not normalized here; KTX2 carries its Vulkan transfer function.
34    pub color_space: TextureColorSpace,
35}
36
37/// Transfer-function information carried across a decode/transcode boundary.
38#[derive(Clone, Copy, Debug, PartialEq, Eq)]
39pub enum TextureColorSpace {
40    Linear,
41    Srgb,
42    /// Basis metadata needs to be interpreted by the eventual transcoder/policy owner.
43    Unknown,
44}
45
46/// A transcode target with an explicit transfer function. `Unknown` is intentional for Basis
47/// payloads whose color metadata has not been interpreted by this crate.
48#[derive(Clone, Copy, Debug, PartialEq, Eq)]
49pub enum TextureTranscodeTarget {
50    Rgba8(TextureColorSpace),
51}
52
53#[derive(Clone, Copy, Debug, PartialEq, Eq)]
54pub enum TextureFallback {
55    /// Keep the verified encoded resource usable while refinement is pending.
56    PreserveEncodedResource,
57}
58
59#[derive(Clone, Copy, Debug, PartialEq, Eq)]
60pub enum TextureRefinementState {
61    PendingTranscode,
62}
63
64#[derive(Clone, Copy, Debug, PartialEq, Eq)]
65pub struct TextureTranscodeRequest {
66    pub source: Ktx2TranscodeSource,
67    pub target: TextureTranscodeTarget,
68    pub fallback: TextureFallback,
69    pub refinement: TextureRefinementState,
70}
71
72/// Allocation-free HMC admission result. A transcode request is not reported as a decoded image;
73/// callers can preserve the source and attach a device/worker-specific refinement later.
74#[derive(Clone, Copy, Debug, PartialEq, Eq)]
75pub enum TextureDecodePlan {
76    DecodeRgba8 {
77        info: DecodedTextureInfo,
78        scratch_bytes: usize,
79    },
80    RequiresTranscode(TextureTranscodeRequest),
81}
82
83#[derive(Clone, Copy, Debug, PartialEq, Eq)]
84pub enum TextureDecodeError {
85    EncodedInputTooLarge,
86    InvalidImage,
87    DimensionsExceedLimit,
88    DecodedImageExceedsLimit,
89    OutputBufferTooSmall,
90    ScratchBufferTooSmall,
91    UnsupportedMime,
92    UnsupportedImageFormat,
93    UnsupportedSupercompression,
94    RequiresTranscode(Ktx2TranscodeSource),
95}
96
97impl std::fmt::Display for TextureDecodeError {
98    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
99        write!(f, "texture decode: {self:?}")
100    }
101}
102
103impl std::error::Error for TextureDecodeError {}
104
105/// Decode a verified HMC texture to tightly packed RGBA8.
106///
107/// `output` and `scratch` are caller-owned. The function never grows either buffer, and fails
108/// before decoding when encoded, dimension, decoded-byte, or caller-buffer limits are exceeded.
109/// PNG and JPEG are supported on native and WASM. KTX2 RGBA8 UNORM/SRGB base levels support
110/// uncompressed data everywhere and bounded Zstd/Zlib expansion on native. Basis and GPU block
111/// formats return a typed transcode refusal; they are never silently treated as RGBA8.
112pub fn decode_hmc_texture_rgba8_into(
113    resource: &HmcTextureResource<'_>,
114    limits: TextureDecodeLimits,
115    output: &mut [u8],
116    scratch: &mut [u8],
117) -> Result<DecodedTextureInfo, TextureDecodeError> {
118    if resource.bytes.len() > limits.max_encoded_bytes {
119        return Err(TextureDecodeError::EncodedInputTooLarge);
120    }
121    super::texture_ingestion::validate_image_signature(resource.mime_type, resource.bytes)
122        .map_err(|e| match e {
123            super::texture_ingestion::TextureIngestionError::UnsupportedMime => {
124                TextureDecodeError::UnsupportedMime
125            }
126            _ => TextureDecodeError::InvalidImage,
127        })?;
128    if mime_matches(resource.mime_type, "image/png") {
129        decode_png_rgba8(resource.bytes, limits, output, scratch)
130    } else if mime_matches(resource.mime_type, "image/jpeg")
131        || mime_matches(resource.mime_type, "image/jpg")
132    {
133        decode_jpeg_rgba8(resource.bytes, limits, output)
134    } else if mime_matches(resource.mime_type, "image/ktx2") {
135        decode_ktx2_rgba8(resource.bytes, limits, output, scratch)
136    } else {
137        Err(TextureDecodeError::UnsupportedMime)
138    }
139}
140
141/// Bounded cold-path convenience for asset loaders that own the destination allocation. The
142/// maximum output and scratch sizes are established from codec metadata before either vector is
143/// allocated; use the `_into` form when the caller already has workspace buffers.
144pub fn decode_hmc_texture_rgba8(
145    resource: &HmcTextureResource<'_>,
146    limits: TextureDecodeLimits,
147) -> Result<(Vec<u8>, DecodedTextureInfo), TextureDecodeError> {
148    let (info, scratch_len) = inspect_hmc_texture_requirements(resource, limits)?;
149    let mut output = vec![0; info.rgba8_bytes];
150    let mut scratch = vec![0; scratch_len];
151    let decoded = decode_hmc_texture_rgba8_into(resource, limits, &mut output, &mut scratch)?;
152    Ok((output, decoded))
153}
154
155/// Validate codec metadata and report exact RGBA8 output and decoder scratch requirements without
156/// allocating or decoding the image. Asset admission can use this to plan texture residency
157/// before materializing pixel buffers.
158pub fn inspect_hmc_texture_requirements(
159    resource: &HmcTextureResource<'_>,
160    limits: TextureDecodeLimits,
161) -> Result<(DecodedTextureInfo, usize), TextureDecodeError> {
162    if resource.bytes.len() > limits.max_encoded_bytes {
163        return Err(TextureDecodeError::EncodedInputTooLarge);
164    }
165    super::texture_ingestion::validate_image_signature(resource.mime_type, resource.bytes)
166        .map_err(|e| match e {
167            super::texture_ingestion::TextureIngestionError::UnsupportedMime => {
168                TextureDecodeError::UnsupportedMime
169            }
170            _ => TextureDecodeError::InvalidImage,
171        })?;
172    if mime_matches(resource.mime_type, "image/png") {
173        let mut decoder = png::Decoder::new_with_limits(
174            resource.bytes,
175            png::Limits {
176                bytes: limits.max_decoded_bytes,
177            },
178        );
179        decoder.set_transformations(png::Transformations::normalize_to_color8());
180        let reader = decoder.read_info().map_err(map_png_error)?;
181        let width = reader.info().width;
182        let height = reader.info().height;
183        let rgba8_bytes = required_rgba_bytes(width, height, limits, usize::MAX)?;
184        let scratch_len = reader.output_buffer_size();
185        if scratch_len > limits.max_decoded_bytes {
186            return Err(TextureDecodeError::DecodedImageExceedsLimit);
187        }
188        Ok((
189            DecodedTextureInfo {
190                width,
191                height,
192                rgba8_bytes,
193                color_space: TextureColorSpace::Unknown,
194            },
195            scratch_len,
196        ))
197    } else if mime_matches(resource.mime_type, "image/jpeg")
198        || mime_matches(resource.mime_type, "image/jpg")
199    {
200        let mut decoder = jpeg_decoder::Decoder::new(resource.bytes);
201        decoder.set_max_decoding_buffer_size(limits.max_decoded_bytes);
202        decoder
203            .read_info()
204            .map_err(|_| TextureDecodeError::InvalidImage)?;
205        let dimensions = decoder.info().ok_or(TextureDecodeError::InvalidImage)?;
206        let width = u32::from(dimensions.width);
207        let height = u32::from(dimensions.height);
208        let rgba8_bytes = required_rgba_bytes(width, height, limits, usize::MAX)?;
209        Ok((
210            DecodedTextureInfo {
211                width,
212                height,
213                rgba8_bytes,
214                color_space: TextureColorSpace::Unknown,
215            },
216            0,
217        ))
218    } else if mime_matches(resource.mime_type, "image/ktx2") {
219        inspect_ktx2_rgba8(resource.bytes, limits)
220    } else {
221        Err(TextureDecodeError::UnsupportedMime)
222    }
223}
224
225/// Inspect a resource for HMC without collapsing a known compressed/Basis source into a generic
226/// decode failure. This is the capability/refinement boundary: only the returned `DecodeRgba8`
227/// branch may be admitted as CPU RGBA8, while the other branch preserves the verified source.
228pub fn inspect_hmc_texture_plan(
229    resource: &HmcTextureResource<'_>,
230    limits: TextureDecodeLimits,
231) -> Result<TextureDecodePlan, TextureDecodeError> {
232    if resource.bytes.len() > limits.max_encoded_bytes {
233        return Err(TextureDecodeError::EncodedInputTooLarge);
234    }
235    super::texture_ingestion::validate_image_signature(resource.mime_type, resource.bytes)
236        .map_err(|e| match e {
237            super::texture_ingestion::TextureIngestionError::UnsupportedMime => {
238                TextureDecodeError::UnsupportedMime
239            }
240            _ => TextureDecodeError::InvalidImage,
241        })?;
242    if !mime_matches(resource.mime_type, "image/ktx2") {
243        let (info, scratch_bytes) = inspect_hmc_texture_requirements(resource, limits)?;
244        return Ok(TextureDecodePlan::DecodeRgba8 {
245            info,
246            scratch_bytes,
247        });
248    }
249
250    let document = super::texture_ktx2::Ktx2Document::parse(resource.bytes)
251        .map_err(|_| TextureDecodeError::InvalidImage)?;
252    let source = document.transcode_source();
253    #[cfg(target_arch = "wasm32")]
254    let source = source.or_else(|| match document.supercompression() {
255        super::texture_ktx2::Ktx2Supercompression::Zstd
256        | super::texture_ktx2::Ktx2Supercompression::Zlib => Some(
257            Ktx2TranscodeSource::Supercompression(document.supercompression()),
258        ),
259        _ => None,
260    });
261    if let Some(source) = source {
262        return Ok(TextureDecodePlan::RequiresTranscode(
263            TextureTranscodeRequest {
264                source,
265                target: TextureTranscodeTarget::Rgba8(TextureColorSpace::from(
266                    document.color_space(),
267                )),
268                fallback: TextureFallback::PreserveEncodedResource,
269                refinement: TextureRefinementState::PendingTranscode,
270            },
271        ));
272    }
273    let (info, scratch_bytes) = inspect_hmc_texture_requirements(resource, limits)?;
274    Ok(TextureDecodePlan::DecodeRgba8 {
275        info,
276        scratch_bytes,
277    })
278}
279
280impl From<Ktx2ColorSpace> for TextureColorSpace {
281    fn from(value: Ktx2ColorSpace) -> Self {
282        match value {
283            Ktx2ColorSpace::Linear => Self::Linear,
284            Ktx2ColorSpace::Srgb => Self::Srgb,
285            Ktx2ColorSpace::Unknown => Self::Unknown,
286        }
287    }
288}
289
290fn mime_matches(actual: &str, expected: &str) -> bool {
291    actual
292        .split(';')
293        .next()
294        .map(str::trim)
295        .is_some_and(|mime| mime.eq_ignore_ascii_case(expected))
296}
297
298fn inspect_ktx2_rgba8(
299    bytes: &[u8],
300    limits: TextureDecodeLimits,
301) -> Result<(DecodedTextureInfo, usize), TextureDecodeError> {
302    use super::texture_ktx2::Ktx2Document;
303
304    let document = Ktx2Document::parse(bytes).map_err(|_| TextureDecodeError::InvalidImage)?;
305    if let Some(source) = document.transcode_source() {
306        return Err(TextureDecodeError::RequiresTranscode(source));
307    }
308    let image =
309        super::texture_ktx2_rgba8::inspect_ktx2_rgba8_base_level_with_compression(&document, true)
310            .map_err(map_ktx2_rgba8_error)?;
311    let rgba8_bytes = required_rgba_bytes(image.width, image.height, limits, usize::MAX)?;
312    if rgba8_bytes != image.byte_len {
313        return Err(TextureDecodeError::InvalidImage);
314    }
315    let scratch_bytes = if document.supercompression_scheme == 0 {
316        0
317    } else {
318        image.byte_len
319    };
320    Ok((
321        DecodedTextureInfo {
322            width: image.width,
323            height: image.height,
324            rgba8_bytes,
325            color_space: TextureColorSpace::from(document.color_space()),
326        },
327        scratch_bytes,
328    ))
329}
330
331fn decode_ktx2_rgba8(
332    bytes: &[u8],
333    limits: TextureDecodeLimits,
334    output: &mut [u8],
335    scratch: &mut [u8],
336) -> Result<DecodedTextureInfo, TextureDecodeError> {
337    use super::texture_ktx2::Ktx2Document;
338    use super::texture_ktx2_rgba8::{decode_ktx2_rgba8_base_level_with_scratch, Rgba8Ktx2Error};
339
340    let document = Ktx2Document::parse(bytes).map_err(|_| TextureDecodeError::InvalidImage)?;
341    if let Some(source) = document.transcode_source() {
342        return Err(TextureDecodeError::RequiresTranscode(source));
343    }
344    let image =
345        super::texture_ktx2_rgba8::inspect_ktx2_rgba8_base_level_with_compression(&document, true)
346            .map_err(map_ktx2_rgba8_error)?;
347    let rgba8_bytes = required_rgba_bytes(image.width, image.height, limits, output.len())?;
348    decode_ktx2_rgba8_base_level_with_scratch(&document, &mut output[..rgba8_bytes], scratch)
349        .map_err(|error| match error {
350            Rgba8Ktx2Error::OutputTooSmall => TextureDecodeError::OutputBufferTooSmall,
351            Rgba8Ktx2Error::CompressedScratchTooSmall => TextureDecodeError::ScratchBufferTooSmall,
352            other => map_ktx2_rgba8_error(other),
353        })?;
354    Ok(DecodedTextureInfo {
355        width: image.width,
356        height: image.height,
357        rgba8_bytes,
358        color_space: TextureColorSpace::from(document.color_space()),
359    })
360}
361
362fn map_ktx2_rgba8_error(error: super::texture_ktx2_rgba8::Rgba8Ktx2Error) -> TextureDecodeError {
363    use super::texture_ktx2_rgba8::Rgba8Ktx2Error;
364    match error {
365        Rgba8Ktx2Error::UnsupportedFormat | Rgba8Ktx2Error::UnsupportedTypeSize => {
366            TextureDecodeError::UnsupportedImageFormat
367        }
368        Rgba8Ktx2Error::UnsupportedSupercompression => {
369            TextureDecodeError::UnsupportedSupercompression
370        }
371        Rgba8Ktx2Error::RequiresTranscode(source) => TextureDecodeError::RequiresTranscode(source),
372        Rgba8Ktx2Error::InvalidCompressedLevel => TextureDecodeError::InvalidImage,
373        Rgba8Ktx2Error::CompressedScratchTooSmall => TextureDecodeError::ScratchBufferTooSmall,
374        Rgba8Ktx2Error::OutputTooSmall => TextureDecodeError::OutputBufferTooSmall,
375        Rgba8Ktx2Error::InvalidDimensions => TextureDecodeError::DecodedImageExceedsLimit,
376        Rgba8Ktx2Error::UnsupportedDimensions
377        | Rgba8Ktx2Error::UnsupportedArray
378        | Rgba8Ktx2Error::UnsupportedFaceCount
379        | Rgba8Ktx2Error::MissingBaseLevel
380        | Rgba8Ktx2Error::InvalidBaseLevelLength => TextureDecodeError::InvalidImage,
381    }
382}
383
384fn required_rgba_bytes(
385    width: u32,
386    height: u32,
387    limits: TextureDecodeLimits,
388    output_len: usize,
389) -> Result<usize, TextureDecodeError> {
390    if width == 0 || height == 0 || width > limits.max_width || height > limits.max_height {
391        return Err(TextureDecodeError::DimensionsExceedLimit);
392    }
393    let bytes = (width as usize)
394        .checked_mul(height as usize)
395        .and_then(|pixels| pixels.checked_mul(4))
396        .ok_or(TextureDecodeError::DecodedImageExceedsLimit)?;
397    if bytes > limits.max_decoded_bytes {
398        return Err(TextureDecodeError::DecodedImageExceedsLimit);
399    }
400    if output_len < bytes {
401        return Err(TextureDecodeError::OutputBufferTooSmall);
402    }
403    Ok(bytes)
404}
405
406fn decode_png_rgba8(
407    bytes: &[u8],
408    limits: TextureDecodeLimits,
409    output: &mut [u8],
410    scratch: &mut [u8],
411) -> Result<DecodedTextureInfo, TextureDecodeError> {
412    let mut decoder = png::Decoder::new_with_limits(
413        bytes,
414        png::Limits {
415            bytes: limits.max_decoded_bytes,
416        },
417    );
418    decoder.set_transformations(png::Transformations::normalize_to_color8());
419    let mut reader = decoder.read_info().map_err(map_png_error)?;
420    let width = reader.info().width;
421    let height = reader.info().height;
422    let rgba_bytes = required_rgba_bytes(width, height, limits, output.len())?;
423    let required_scratch = reader.output_buffer_size();
424    if required_scratch > limits.max_decoded_bytes {
425        return Err(TextureDecodeError::DecodedImageExceedsLimit);
426    }
427    if scratch.len() < required_scratch {
428        return Err(TextureDecodeError::ScratchBufferTooSmall);
429    }
430    let info = reader.next_frame(scratch).map_err(map_png_error)?;
431    if info.width != width || info.height != height {
432        return Err(TextureDecodeError::InvalidImage);
433    }
434
435    let channels = match info.color_type {
436        png::ColorType::Rgb => 3,
437        png::ColorType::Rgba => 4,
438        png::ColorType::Grayscale => 1,
439        png::ColorType::GrayscaleAlpha => 2,
440        png::ColorType::Indexed => return Err(TextureDecodeError::InvalidImage),
441    };
442    let width_usize = width as usize;
443    let height_usize = height as usize;
444    let row_bytes = width_usize
445        .checked_mul(channels)
446        .ok_or(TextureDecodeError::DecodedImageExceedsLimit)?;
447    if info.line_size < row_bytes || info.buffer_size() > scratch.len() {
448        return Err(TextureDecodeError::InvalidImage);
449    }
450    for y in 0..height_usize {
451        let row = &scratch[y * info.line_size..y * info.line_size + row_bytes];
452        for x in 0..width_usize {
453            let src = x * channels;
454            let dst = (y * width_usize + x) * 4;
455            match channels {
456                1 => output[dst..dst + 4].copy_from_slice(&[row[src], row[src], row[src], 255]),
457                2 => output[dst..dst + 4].copy_from_slice(&[
458                    row[src],
459                    row[src],
460                    row[src],
461                    row[src + 1],
462                ]),
463                3 => output[dst..dst + 4].copy_from_slice(&[
464                    row[src],
465                    row[src + 1],
466                    row[src + 2],
467                    255,
468                ]),
469                4 => output[dst..dst + 4].copy_from_slice(&row[src..src + 4]),
470                _ => unreachable!(),
471            }
472        }
473    }
474    Ok(DecodedTextureInfo {
475        width,
476        height,
477        rgba8_bytes: rgba_bytes,
478        color_space: TextureColorSpace::Unknown,
479    })
480}
481
482fn map_png_error(error: png::DecodingError) -> TextureDecodeError {
483    match error {
484        png::DecodingError::LimitsExceeded => TextureDecodeError::DecodedImageExceedsLimit,
485        _ => TextureDecodeError::InvalidImage,
486    }
487}
488
489fn decode_jpeg_rgba8(
490    bytes: &[u8],
491    limits: TextureDecodeLimits,
492    output: &mut [u8],
493) -> Result<DecodedTextureInfo, TextureDecodeError> {
494    let mut decoder = jpeg_decoder::Decoder::new(bytes);
495    decoder.set_max_decoding_buffer_size(limits.max_decoded_bytes);
496    decoder
497        .read_info()
498        .map_err(|_| TextureDecodeError::InvalidImage)?;
499    let dimensions = decoder.info().ok_or(TextureDecodeError::InvalidImage)?;
500    let width = u32::from(dimensions.width);
501    let height = u32::from(dimensions.height);
502    let rgba_bytes = required_rgba_bytes(width, height, limits, output.len())?;
503    let pixels = decoder
504        .decode()
505        .map_err(|_| TextureDecodeError::InvalidImage)?;
506    let count = (width as usize)
507        .checked_mul(height as usize)
508        .ok_or(TextureDecodeError::DecodedImageExceedsLimit)?;
509    match dimensions.pixel_format {
510        jpeg_decoder::PixelFormat::RGB24 => {
511            if pixels.len()
512                != count
513                    .checked_mul(3)
514                    .ok_or(TextureDecodeError::DecodedImageExceedsLimit)?
515            {
516                return Err(TextureDecodeError::InvalidImage);
517            }
518            for (src, dst) in pixels
519                .chunks_exact(3)
520                .zip(output[..rgba_bytes].chunks_exact_mut(4))
521            {
522                dst.copy_from_slice(&[src[0], src[1], src[2], 255]);
523            }
524        }
525        jpeg_decoder::PixelFormat::L8 => {
526            if pixels.len() != count {
527                return Err(TextureDecodeError::InvalidImage);
528            }
529            for (&gray, dst) in pixels.iter().zip(output[..rgba_bytes].chunks_exact_mut(4)) {
530                dst.copy_from_slice(&[gray, gray, gray, 255]);
531            }
532        }
533        jpeg_decoder::PixelFormat::L16 | jpeg_decoder::PixelFormat::CMYK32 => {
534            return Err(TextureDecodeError::UnsupportedMime);
535        }
536    }
537    Ok(DecodedTextureInfo {
538        width,
539        height,
540        rgba8_bytes: rgba_bytes,
541        color_space: TextureColorSpace::Unknown,
542    })
543}
544
545#[cfg(test)]
546#[path = "texture_decode_tests.rs"]
547mod tests;