1use 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 pub color_space: TextureColorSpace,
35}
36
37#[derive(Clone, Copy, Debug, PartialEq, Eq)]
39pub enum TextureColorSpace {
40 Linear,
41 Srgb,
42 Unknown,
44}
45
46#[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 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#[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
105pub 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
141pub 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
155pub 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
225pub 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;