1use crate::volumetric_texture::coarse_texture_level;
4use qualia_core_db::container_10d::{
5 decode_material_section_into, decode_mesh_section, material_section_counts, Container10dHeader,
6 MaterialRecord, OpacityMode, SectionDescriptor, SectionType, SubmeshRange,
7};
8use qualia_core_db::render::gpu::{TextureColorSpace, TextureMipSemantic, TextureUploadError};
9use qualia_core_db::render::texture_ktx2::Ktx2Document;
10use qualia_core_db::render::texture_stream_policy::{
11 plan_texture_residency_partial, TextureStreamAction, TextureStreamActionKind,
12 TextureStreamBudget, TextureStreamDemand,
13};
14use qualia_core_db::render::texture_streaming_plan::{
15 decode_rgba8_ktx2_mip_into, rgba8_ktx2_mip_candidate, reserve_texture_mip,
16 select_texture_mip, Ktx2MipCandidateError, TextureMipBackendCost, TextureMipBudget,
17 TextureMipCandidate,
18};
19use std::collections::{BTreeMap, BTreeSet};
20
21#[path = "volumetric_hmc_stream.rs"]
22mod volumetric_hmc_stream;
23
24pub use self::volumetric_hmc_stream::{
25 HmcTextureResidencyRequest, HmcTextureStreamApplyRequest, HmcTextureStreamPlan,
26};
27use self::volumetric_hmc_stream::HmcTextureStreamEntry;
28use self::volumetric_hmc_stream::{
29 HMC_TEXTURE_STREAM_MAX_ENTRIES, HMC_TEXTURE_STREAM_STATE_MAX_BYTES,
30};
31pub(crate) use self::volumetric_hmc_stream::HmcTextureStreamState;
32
33const HMC_KTX2_MAX_DECODED_BYTES: u64 = 256 * 1024 * 1024;
34
35#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
36pub(crate) struct TextureUse {
37 pub(crate) color_space: TextureColorSpace,
38 pub(crate) mip_semantic: TextureMipSemantic,
39}
40
41#[derive(Clone, Copy)]
42pub(crate) struct HmcTexturePlanEntry {
43 pub(crate) semantic_id: u64,
44 pub(crate) digest: [u8; 32],
45 pub(crate) texture_use: TextureUse,
46 pub(crate) width: u32,
47 pub(crate) height: u32,
48 pub(crate) mip_count: u8,
49 pub(crate) supported_mips: u32,
50}
51
52#[derive(Clone, Copy, Debug, PartialEq, Eq)]
53enum Ktx2HmcFallback {
54 Parse,
55 Candidate(Ktx2MipCandidateError),
56 ColorSpaceMismatch,
57 NoAffordableLevel,
58 Decode,
59}
60
61fn note_ktx2_fallback(
62 report: &mut super::HmcTextureAdmissionReport,
63 fallback: Ktx2HmcFallback,
64 mip_bytes: u64,
65) {
66 report.deferred_interpretations += 1;
67 if matches!(
68 fallback,
69 Ktx2HmcFallback::Parse
70 | Ktx2HmcFallback::Candidate(_)
71 | Ktx2HmcFallback::ColorSpaceMismatch
72 ) {
73 report.capability_refusals += 1;
74 }
75 if matches!(fallback, Ktx2HmcFallback::NoAffordableLevel | Ktx2HmcFallback::Decode) {
76 report.deferred_mips += 1;
77 report.deferred_upload_bytes = report.deferred_upload_bytes.saturating_add(mip_bytes);
78 }
79}
80
81fn ktx2_backend_cost(
82 document: &Ktx2Document<'_>,
83 level_index: usize,
84) -> Result<TextureMipBackendCost, Ktx2MipCandidateError> {
85 let mut width = document
86 .pixel_width
87 .checked_shr(level_index as u32)
88 .unwrap_or(0)
89 .max(1);
90 let mut height = document
91 .pixel_height
92 .checked_shr(level_index as u32)
93 .unwrap_or(0)
94 .max(1);
95 let mut resident_bytes = 0u64;
96 loop {
97 let level_bytes = u64::from(width)
98 .checked_mul(u64::from(height))
99 .and_then(|pixels| pixels.checked_mul(4))
100 .ok_or(Ktx2MipCandidateError::SizeOverflow)?;
101 resident_bytes = resident_bytes
102 .checked_add(level_bytes)
103 .ok_or(Ktx2MipCandidateError::SizeOverflow)?;
104 if width == 1 && height == 1 {
105 break;
106 }
107 width = (width / 2).max(1);
108 height = (height / 2).max(1);
109 }
110 let upload_staging_bytes = document
111 .level(level_index)
112 .ok_or(Ktx2MipCandidateError::InvalidLevel)?
113 .bytes
114 .len() as u64;
115 Ok(TextureMipBackendCost {
116 gpu_resident_bytes: resident_bytes,
117 upload_staging_bytes,
118 })
119}
120
121fn ktx2_rgba8_candidates(
122 document: &Ktx2Document<'_>,
123) -> Result<Vec<TextureMipCandidate>, Ktx2MipCandidateError> {
124 let mut candidates = Vec::new();
125 candidates
126 .try_reserve_exact(document.level_count())
127 .map_err(|_| Ktx2MipCandidateError::SizeOverflow)?;
128 for level_index in 0..document.level_count() {
129 let backend_cost = ktx2_backend_cost(document, level_index)?;
130 if let Ok(candidate) = rgba8_ktx2_mip_candidate(document, level_index, backend_cost) {
131 candidates.push(candidate);
132 }
133 }
134 if candidates.is_empty() {
135 return Err(rgba8_ktx2_mip_candidate(
136 document,
137 0,
138 TextureMipBackendCost {
139 gpu_resident_bytes: 0,
140 upload_staging_bytes: 0,
141 },
142 )
143 .err()
144 .unwrap_or(Ktx2MipCandidateError::InvalidLevel));
145 }
146 Ok(candidates)
147}
148
149fn select_hmc_ktx2_level(
150 document: &Ktx2Document<'_>,
151 texture_use: TextureUse,
152 request: HmcTextureStreamRequest,
153 remaining: TextureMipBudget,
154) -> Result<TextureMipCandidate, Ktx2HmcFallback> {
155 let candidates = ktx2_rgba8_candidates(document).map_err(Ktx2HmcFallback::Candidate)?;
156 let is_srgb = document.vk_format == 43;
157 if (texture_use.color_space == TextureColorSpace::Srgb) != is_srgb {
158 return Err(Ktx2HmcFallback::ColorSpaceMismatch);
159 }
160 let projected_width = if request.projected_width == 0 {
161 document.pixel_width
162 } else {
163 request.projected_width
164 };
165 let projected_height = if request.projected_height == 0 {
166 document.pixel_height.max(1)
167 } else {
168 request.projected_height
169 };
170 select_texture_mip(
171 &candidates,
172 projected_width,
173 projected_height,
174 remaining,
175 )
176 .map(|selection| selection.candidate)
177 .ok_or(Ktx2HmcFallback::NoAffordableLevel)
178}
179
180#[derive(Clone, Copy, Debug, Eq, PartialEq)]
182pub struct HmcTextureStreamRequest {
183 pub budget: TextureStreamBudget,
184 pub projected_width: u32,
186 pub projected_height: u32,
188}
189
190impl Default for HmcTextureStreamRequest {
191 fn default() -> Self {
192 Self {
193 budget: TextureStreamBudget {
194 max_resident_bytes: u64::MAX,
195 max_upload_bytes: u64::MAX,
196 },
197 projected_width: 0,
198 projected_height: 0,
199 }
200 }
201}
202
203pub(crate) fn is_ktx2_mime(mime: &str) -> bool {
205 mime.split(';')
206 .next()
207 .map(str::trim)
208 .is_some_and(|m| m.eq_ignore_ascii_case("image/ktx2"))
209}
210
211const HMC_WATER_MAX_VERTICES: usize = 1_048_576;
212const HMC_WATER_MAX_INDICES: usize = 3_145_728;
213const HMC_WATER_DEFAULT_MAX_GEOMETRY_BYTES: u64 = 64 * 1024 * 1024;
214
215#[derive(Clone, Copy, Debug, PartialEq, Eq)]
219pub struct HmcWaterLoadPolicy {
220 pub max_geometry_bytes: u64,
221 pub preferred_quality: u32,
223}
224
225impl Default for HmcWaterLoadPolicy {
226 fn default() -> Self {
227 Self {
228 max_geometry_bytes: HMC_WATER_DEFAULT_MAX_GEOMETRY_BYTES,
229 preferred_quality: 2,
230 }
231 }
232}
233
234pub(crate) fn validate_hmc_water_geometry(
236 positions: &[[f32; 3]],
237 triangles: &[[u32; 3]],
238 max_bytes: u64,
239) -> Result<u64, String> {
240 if positions.is_empty()
241 || triangles.is_empty()
242 || positions.len() > HMC_WATER_MAX_VERTICES
243 || triangles.len().saturating_mul(3) > HMC_WATER_MAX_INDICES
244 {
245 return Err("HMC water geometry exceeds bounded admission limits".to_string());
246 }
247 if positions
248 .iter()
249 .any(|position| position.iter().any(|value| !value.is_finite()))
250 {
251 return Err("HMC water geometry contains non-finite positions".to_string());
252 }
253 if triangles.iter().any(|triangle| {
254 triangle
255 .iter()
256 .any(|&index| index as usize >= positions.len())
257 }) {
258 return Err("HMC water geometry contains an out-of-range index".to_string());
259 }
260 let bytes = (positions.len() as u64)
261 .checked_mul(20)
262 .and_then(|value| value.checked_add((triangles.len() as u64).checked_mul(3 * 4)?))
263 .ok_or_else(|| "HMC water geometry byte size overflow".to_string())?;
264 if bytes > max_bytes {
265 return Err(format!(
266 "HMC water geometry exceeds admission budget: {bytes} > {max_bytes} bytes"
267 ));
268 }
269 Ok(bytes)
270}
271
272pub(crate) fn select_hmc_water_quality(
274 triangle_count: usize,
275 geometry_bytes: u64,
276 preferred_quality: u32,
277) -> u32 {
278 let preferred_quality = preferred_quality.min(2);
279 if preferred_quality == 0 {
280 return 0;
281 }
282 if triangle_count > 750_000 || geometry_bytes > 32 * 1024 * 1024 {
285 0
286 } else if triangle_count > 250_000 || geometry_bytes > 12 * 1024 * 1024 {
287 preferred_quality.min(1)
288 } else {
289 preferred_quality
290 }
291}
292
293fn extract_texture_uses(
294 asset_bytes: &[u8],
295 descs: &[SectionDescriptor],
296) -> Result<BTreeMap<[u8; 32], BTreeSet<TextureUse>>, String> {
297 let mut uses = BTreeMap::<[u8; 32], BTreeSet<TextureUse>>::new();
298 let mat_desc = descs
299 .iter()
300 .find(|d| d.typ() == Some(SectionType::Materials));
301 let Some(descriptor) = mat_desc else {
302 return Ok(uses);
303 };
304 let start = descriptor.byte_offset as usize;
305 let end = start
306 .checked_add(descriptor.byte_length as usize)
307 .filter(|&end| end <= asset_bytes.len())
308 .ok_or_else(|| "10d MAT1 section is outside asset bytes".to_string())?;
309 let payload = &asset_bytes[start..end];
310 let (mat_count, range_count) =
311 material_section_counts(payload).map_err(|e| format!("10d MAT1 header: {e}"))?;
312 let mut materials = vec![MaterialRecord::legacy_default(); mat_count];
313 let first_mat_id = materials
314 .first()
315 .ok_or_else(|| "10d MAT1 section has no materials".to_string())?
316 .id;
317 let mut ranges = vec![
318 SubmeshRange {
319 first_index: 0,
320 index_count: 3,
321 material_id: first_mat_id,
322 semantic_id: 0,
323 };
324 range_count
325 ];
326 let mesh_index_count = descs
327 .iter()
328 .find(|d| d.typ() == Some(SectionType::QuantizedMesh))
329 .map(|d| {
330 let start = d.byte_offset as usize;
331 let end = start + d.byte_length as usize;
332 decode_mesh_section(&asset_bytes[start..end])
333 .map(|m| m.triangles.len().saturating_mul(3) as u32)
334 .map_err(|e| format!("10d mesh decode: {e}"))
335 })
336 .transpose()?
337 .ok_or_else(|| "10d asset has no QuantizedMesh section".to_string())?;
338
339 decode_material_section_into(payload, mesh_index_count, &mut materials, &mut ranges)
340 .map_err(|e| format!("10d MAT1 decode: {e}"))?;
341
342 let mut add_use =
343 |digest: [u8; 32], color_space: TextureColorSpace, mip_semantic: TextureMipSemantic| {
344 if digest != [0; 32] {
345 uses.entry(digest).or_default().insert(TextureUse {
346 color_space,
347 mip_semantic,
348 });
349 }
350 };
351
352 for mat in &materials {
353 let base_mip = if mat.opacity_mode == OpacityMode::Mask {
354 TextureMipSemantic::alpha_mask(mat.alpha_cutoff).unwrap_or(TextureMipSemantic::Color)
355 } else {
356 TextureMipSemantic::Color
357 };
358 add_use(mat.base_color_texture, TextureColorSpace::Srgb, base_mip);
359 add_use(
360 mat.emissive_texture,
361 TextureColorSpace::Srgb,
362 TextureMipSemantic::Color,
363 );
364 add_use(
365 mat.normal_texture,
366 TextureColorSpace::Linear,
367 TextureMipSemantic::Normal,
368 );
369 add_use(
370 mat.metallic_roughness_texture,
371 TextureColorSpace::Linear,
372 TextureMipSemantic::LinearData,
373 );
374 add_use(
375 mat.occlusion_texture,
376 TextureColorSpace::Linear,
377 TextureMipSemantic::LinearData,
378 );
379 add_use(
380 mat.stylized_ramp_texture,
381 TextureColorSpace::Srgb,
382 TextureMipSemantic::Color,
383 );
384 }
385 Ok(uses)
386}
387
388fn note_refusal(report: &mut super::HmcTextureAdmissionReport, mip_count: usize, mip_bytes: u64) {
389 report.admitted_mips = report.admitted_mips.saturating_sub(mip_count);
390 report.deferred_mips += mip_count;
391 report.admitted_upload_bytes = report.admitted_upload_bytes.saturating_sub(mip_bytes);
392 report.deferred_upload_bytes = report.deferred_upload_bytes.saturating_add(mip_bytes);
393 report.deferred_interpretations += 1;
394}
395
396fn rgba8_resident_bytes(width: u32, height: u32, first_mip: u8) -> Result<u64, String> {
397 let mut width = width.max(1);
398 let mut height = height.max(1);
399 for _ in 0..first_mip {
400 width = (width / 2).max(1);
401 height = (height / 2).max(1);
402 }
403 let mut total = 0u64;
404 loop {
405 total = total
406 .checked_add(
407 u64::from(width)
408 .checked_mul(u64::from(height))
409 .and_then(|pixels| pixels.checked_mul(4))
410 .ok_or_else(|| "texture resident byte size overflow".to_string())?,
411 )
412 .ok_or_else(|| "texture resident byte size overflow".to_string())?;
413 if width == 1 && height == 1 {
414 return Ok(total);
415 }
416 width = (width / 2).max(1);
417 height = (height / 2).max(1);
418 }
419}
420
421fn build_texture_stream_state(
422 hmc_bytes: &[u8],
423 asset_bytes: &[u8],
424 entries: &[HmcTexturePlanEntry],
425 loaded_residency: &BTreeMap<([u8; 32], TextureUse), (u8, u64)>,
426) -> Result<HmcTextureStreamState, String> {
427 if entries.len() > HMC_TEXTURE_STREAM_MAX_ENTRIES {
428 return Err(format!(
429 "HMC texture stream entry count exceeds bounded limit: {} > {}",
430 entries.len(), HMC_TEXTURE_STREAM_MAX_ENTRIES
431 ));
432 }
433 let retained_bytes = hmc_bytes
434 .len()
435 .checked_add(asset_bytes.len())
436 .ok_or_else(|| "HMC texture stream state size overflow".to_string())?;
437 if retained_bytes > HMC_TEXTURE_STREAM_STATE_MAX_BYTES {
438 return Err(format!(
439 "HMC texture stream state exceeds bounded retention limit: {} > {} bytes",
440 retained_bytes, HMC_TEXTURE_STREAM_STATE_MAX_BYTES
441 ));
442 }
443 let mut retained_bundle = Vec::new();
444 retained_bundle
445 .try_reserve_exact(hmc_bytes.len())
446 .map_err(|_| "HMC texture stream state allocation refused".to_string())?;
447 retained_bundle.extend_from_slice(hmc_bytes);
448 let mut retained_asset = Vec::new();
449 retained_asset
450 .try_reserve_exact(asset_bytes.len())
451 .map_err(|_| "HMC texture asset retention allocation refused".to_string())?;
452 retained_asset.extend_from_slice(asset_bytes);
453 let mut state_entries = Vec::new();
454 state_entries
455 .try_reserve_exact(entries.len())
456 .map_err(|_| "HMC texture stream entry allocation refused".to_string())?;
457 for entry in entries {
458 let (resident_finest_mip, resident_bytes) = loaded_residency
459 .get(&(entry.digest, entry.texture_use))
460 .copied()
461 .map_or((None, 0), |(mip, bytes)| (Some(mip), bytes));
462 state_entries.push(HmcTextureStreamEntry {
463 semantic_id: entry.semantic_id,
464 digest: entry.digest,
465 texture_use: entry.texture_use,
466 width: entry.width,
467 height: entry.height,
468 mip_count: entry.mip_count,
469 supported_mips: entry.supported_mips,
470 resident_finest_mip,
471 resident_bytes,
472 });
473 }
474 Ok(HmcTextureStreamState {
475 bundle_bytes: retained_bundle,
476 asset_bytes: retained_asset,
477 entries: state_entries,
478 generation: 0,
479 })
480}
481
482fn evict_replaced_asset_textures(
483 renderer: &mut super::VolumetricRenderer,
484 next_entries: &[HmcTexturePlanEntry],
485) {
486 let Some(previous_entries) = renderer
487 .texture_stream_state
488 .as_ref()
489 .map(|state| state.entries.clone())
490 else {
491 return;
492 };
493 for entry in &previous_entries {
494 if entry.resident_finest_mip.is_some()
495 && !next_entries.iter().any(|next| {
496 next.digest == entry.digest && next.texture_use == entry.texture_use
497 })
498 {
499 renderer.inner.evict_resident_texture_with_mips(
500 &entry.digest,
501 entry.texture_use.color_space,
502 entry.texture_use.mip_semantic,
503 );
504 }
505 }
506}
507
508pub fn load_hmc_asset_with_texture_request(
510 renderer: &mut super::VolumetricRenderer,
511 hmc_bytes: &[u8],
512 asset_key: &str,
513 request: HmcTextureStreamRequest,
514) -> Result<((u32, u32, f32), super::HmcTextureAdmissionReport), String> {
515 if hmc_bytes.len() > HMC_TEXTURE_STREAM_STATE_MAX_BYTES {
516 return Err(format!(
517 "HMC texture stream state exceeds bounded retention limit: {} > {} bytes",
518 hmc_bytes.len(), HMC_TEXTURE_STREAM_STATE_MAX_BYTES
519 ));
520 }
521 let bundle = qualia_core_db::bundle::BundleReader::parse(hmc_bytes)
522 .map_err(|e| format!("HMC bundle: {e}"))?;
523 let asset_bytes = bundle
524 .get(asset_key)
525 .ok_or_else(|| format!("HMC asset is missing: {asset_key}"))?;
526 let retained_bytes = hmc_bytes
527 .len()
528 .checked_add(asset_bytes.len())
529 .ok_or_else(|| "HMC texture stream state size overflow".to_string())?;
530 if retained_bytes > HMC_TEXTURE_STREAM_STATE_MAX_BYTES {
531 return Err(format!(
532 "HMC texture stream state exceeds bounded retention limit: {} > {} bytes",
533 retained_bytes, HMC_TEXTURE_STREAM_STATE_MAX_BYTES
534 ));
535 }
536 if !bundle.verify_entry(asset_key) {
537 return Err(format!("HMC asset digest check failed: {asset_key}"));
538 }
539 let entry = bundle
540 .entry(asset_key)
541 .ok_or_else(|| format!("HMC asset index entry is missing: {asset_key}"))?;
542 if entry.kind != "10d" {
543 return Err(format!(
544 "HMC asset {asset_key} has kind {:?}, expected 10d",
545 entry.kind
546 ));
547 }
548
549 let header = Container10dHeader::parse(asset_bytes).map_err(|e| format!("10d header: {e}"))?;
550 if qualia_core_db::container_10d::compute_whole_file_crc32c(asset_bytes) != header.header_crc32c
551 {
552 return Err("10d whole-file integrity check failed".to_string());
553 }
554 let descs = qualia_core_db::container_10d::parse_section_table(asset_bytes, &header)
555 .map_err(|e| format!("10d section table: {e}"))?;
556 let texture_uses = extract_texture_uses(asset_bytes, &descs)?;
557
558 let mut plan_entries = Vec::new();
559 let mut ktx2_entries = Vec::new();
560 let mut demands = Vec::new();
561 let mut next_semantic_id = 1u64;
562 let mut report = super::HmcTextureAdmissionReport::default();
563 let mut loaded_residency = BTreeMap::<([u8; 32], TextureUse), (u8, u64)>::new();
564 for (digest, uses) in &texture_uses {
565 let resource =
566 qualia_core_db::render::asset_package::resolve_hmc_texture_resource(&bundle, digest)
567 .map_err(|e| format!("HMC texture resolution: {e}"))?;
568
569 if is_ktx2_mime(resource.mime_type) {
573 let document = match Ktx2Document::parse(resource.bytes) {
574 Ok(document) => document,
575 Err(_) => {
576 report.requested_interpretations += uses.len();
577 for _ in uses {
578 note_ktx2_fallback(&mut report, Ktx2HmcFallback::Parse, 0);
579 }
580 continue;
581 }
582 };
583 let candidates = ktx2_rgba8_candidates(&document);
584 let candidate_error = candidates.as_ref().err().copied();
585 let supported_mips = candidates.as_ref().ok().map(|candidates| {
586 candidates.iter().fold(0u32, |mask, candidate| {
587 mask | (1u32 << candidate.level)
588 })
589 });
590 for texture_use in uses {
591 report.requested_interpretations += 1;
592 if renderer
593 .inner
594 .resident_texture_binding_with_mips(
595 digest,
596 texture_use.color_space,
597 texture_use.mip_semantic,
598 )
599 .is_some()
600 {
601 report.resident_interpretations += 1;
602 continue;
603 }
604 if let Some(error) = candidate_error {
605 note_ktx2_fallback(
606 &mut report,
607 Ktx2HmcFallback::Candidate(error),
608 0,
609 );
610 continue;
611 }
612 if (texture_use.color_space == TextureColorSpace::Srgb)
613 != (document.vk_format == 43)
614 {
615 note_ktx2_fallback(&mut report, Ktx2HmcFallback::ColorSpaceMismatch, 0);
616 continue;
617 }
618 let semantic_id = next_semantic_id;
619 next_semantic_id = next_semantic_id
620 .checked_add(1)
621 .ok_or_else(|| "overflow".to_string())?;
622 ktx2_entries.push(HmcTexturePlanEntry {
623 semantic_id,
624 digest: *digest,
625 texture_use: *texture_use,
626 width: document.pixel_width,
627 height: document.pixel_height.max(1),
628 mip_count: u8::try_from(document.level_count())
629 .map_err(|_| "KTX2 mip count exceeds u8".to_string())?,
630 supported_mips: supported_mips.unwrap_or(0),
631 });
632 }
633 continue;
634 }
635
636 let (info, _) =
637 match qualia_core_db::render::texture_decode::inspect_hmc_texture_requirements(
638 &resource,
639 qualia_core_db::render::texture_decode::TextureDecodeLimits::default(),
640 ) {
641 Ok(reqs) => reqs,
642 Err(_) => {
643 report.requested_interpretations += uses.len();
644 report.deferred_interpretations += uses.len();
645 continue;
646 }
647 };
648 let max_dim = info.width.max(info.height);
649 let mip_count = (u32::BITS - max_dim.leading_zeros()) as u8;
650
651 let desired_finest_mip = if request.projected_width > 0 && request.projected_height > 0 {
652 let mut level = 0u8;
653 while level + 1 < mip_count {
654 let next_w = (info.width >> (level + 1)).max(1);
655 let next_h = (info.height >> (level + 1)).max(1);
656 if next_w >= request.projected_width && next_h >= request.projected_height {
657 level += 1;
658 } else {
659 break;
660 }
661 }
662 level
663 } else {
664 0
665 };
666
667 for texture_use in uses {
668 report.requested_interpretations += 1;
669 if renderer
670 .inner
671 .resident_texture_binding_with_mips(
672 digest,
673 texture_use.color_space,
674 texture_use.mip_semantic,
675 )
676 .is_some()
677 {
678 report.resident_interpretations += 1;
679 continue;
680 }
681 let semantic_id = next_semantic_id;
682 next_semantic_id = next_semantic_id
683 .checked_add(1)
684 .ok_or_else(|| "overflow".to_string())?;
685 let importance = match texture_use.mip_semantic {
686 TextureMipSemantic::Color => 250,
687 TextureMipSemantic::AlphaMask { .. } => 240,
688 TextureMipSemantic::Normal => 220,
689 TextureMipSemantic::LinearData => 200,
690 };
691 demands.push(TextureStreamDemand {
692 semantic_id,
693 width: info.width,
694 height: info.height,
695 mip_count,
696 block_width: 1,
697 block_height: 1,
698 bytes_per_block: 4,
699 desired_finest_mip,
700 resident_finest_mip: None,
701 resident_bytes: 0,
702 requested: true,
703 pinned: false,
704 visible: true,
705 importance,
706 distance_key: 0,
707 last_used_frame: 0,
708 });
709 plan_entries.push(HmcTexturePlanEntry {
710 semantic_id,
711 digest: *digest,
712 texture_use: *texture_use,
713 width: info.width,
714 height: info.height,
715 mip_count,
716 supported_mips: if mip_count == 32 {
717 u32::MAX
718 } else {
719 (1u32 << mip_count) - 1
720 },
721 });
722 }
723 }
724
725 let action_capacity = demands.iter().try_fold(0usize, |total, demand| {
726 total
727 .checked_add(demand.mip_count as usize)
728 .ok_or_else(|| "overflow".to_string())
729 })?;
730 let mut actions = Vec::new();
731 actions
732 .try_reserve_exact(action_capacity)
733 .map_err(|_| "OOM".to_string())?;
734 actions.resize(
735 action_capacity,
736 TextureStreamAction {
737 semantic_id: 0,
738 kind: TextureStreamActionKind::RequestMip,
739 mip_level: 0,
740 bytes: 0,
741 },
742 );
743 let plan = plan_texture_residency_partial(&demands, request.budget, &mut actions)
744 .map_err(|e| format!("HMC texture budget plan: {e:?}"))?;
745 report.admitted_mips = plan.admitted_mip_count;
746 report.deferred_mips = plan.deferred_mip_count;
747 report.admitted_upload_bytes = plan.admitted_upload_bytes;
748 report.deferred_upload_bytes = plan.deferred_upload_bytes;
749 let actions = &actions[..plan.action_count];
750
751 let mut newly_resident = Vec::new();
752 let upload_result = (|| -> Result<(), String> {
753 let mut ktx2_budget = TextureMipBudget {
760 decoded_cpu_bytes: HMC_KTX2_MAX_DECODED_BYTES,
761 gpu_resident_bytes: request
762 .budget
763 .max_resident_bytes
764 .saturating_sub(plan.projected_resident_bytes),
765 upload_staging_bytes: request
766 .budget
767 .max_upload_bytes
768 .saturating_sub(plan.admitted_upload_bytes),
769 per_frame_upload_bytes: request
770 .budget
771 .max_upload_bytes
772 .saturating_sub(plan.admitted_upload_bytes),
773 };
774 for entry in ktx2_entries.iter().copied() {
775 let resource = qualia_core_db::render::asset_package::resolve_hmc_texture_resource(
776 &bundle,
777 &entry.digest,
778 )
779 .map_err(|e| format!("HMC texture resolution: {e}"))?;
780 let document = Ktx2Document::parse(resource.bytes)
781 .map_err(|_| format!("HMC KTX2 fallback: {:?}", Ktx2HmcFallback::Parse))?;
782 let candidate = match select_hmc_ktx2_level(
783 &document,
784 entry.texture_use,
785 request,
786 ktx2_budget,
787 ) {
788 Ok(candidate) => candidate,
789 Err(fallback) => {
790 note_ktx2_fallback(&mut report, fallback, 0);
791 continue;
792 }
793 };
794 let mut candidate_budget = ktx2_budget;
795 if !reserve_texture_mip(candidate, &mut candidate_budget) {
796 note_ktx2_fallback(
797 &mut report,
798 Ktx2HmcFallback::NoAffordableLevel,
799 candidate.upload_bytes,
800 );
801 continue;
802 }
803 let output_len = usize::try_from(candidate.decoded_cpu_bytes)
804 .map_err(|_| "HMC KTX2 selected level is too large".to_string())?;
805 let mut selected_level = vec![0u8; output_len];
806 if decode_rgba8_ktx2_mip_into(&document, candidate.level as usize, &mut selected_level)
807 .is_err()
808 {
809 note_ktx2_fallback(
810 &mut report,
811 Ktx2HmcFallback::Decode,
812 candidate.upload_bytes,
813 );
814 continue;
815 }
816 ktx2_budget = candidate_budget;
817 match renderer
818 .inner
819 .upload_resident_texture_rgba8_at_mip_with_mips(
820 entry.digest,
821 entry.texture_use.color_space,
822 entry.texture_use.mip_semantic,
823 entry.width,
824 entry.height,
825 candidate.level,
826 &selected_level,
827 )
828 {
829 Ok(_) => {
830 newly_resident.push((entry.digest, entry.texture_use));
831 loaded_residency.insert(
832 (entry.digest, entry.texture_use),
833 (candidate.level as u8, candidate.gpu_resident_bytes),
834 );
835 report.resident_interpretations += 1;
836 report.admitted_mips += 1;
837 report.admitted_upload_bytes = report
838 .admitted_upload_bytes
839 .saturating_add(candidate.upload_bytes);
840 }
841 Err(TextureUploadError::GpuBudgetRefused)
842 | Err(TextureUploadError::UploadBudgetRefused) => {
843 note_ktx2_fallback(
844 &mut report,
845 Ktx2HmcFallback::NoAffordableLevel,
846 candidate.upload_bytes,
847 );
848 }
849 Err(e) => return Err(format!("HMC texture upload: {e}")),
850 }
851 }
852
853 for digest in texture_uses.keys() {
854 let mut selected = Vec::new();
855 for entry in plan_entries.iter().filter(|e| e.digest == *digest) {
856 let mut first_mip = None;
857 let mut mip_bytes = 0u64;
858 let mut mip_count = 0usize;
859 for action in actions.iter().filter(|a| {
860 a.semantic_id == entry.semantic_id
861 && a.kind == TextureStreamActionKind::RequestMip
862 }) {
863 first_mip =
864 Some(first_mip.map_or(action.mip_level, |c: u8| c.min(action.mip_level)));
865 mip_bytes = mip_bytes.saturating_add(action.bytes);
866 mip_count += 1;
867 }
868 if let Some(first_mip) = first_mip {
869 selected.push((*entry, first_mip, mip_bytes, mip_count));
870 } else {
871 report.deferred_interpretations += 1;
872 }
873 }
874 if selected.is_empty() {
875 continue;
876 }
877 let resource = qualia_core_db::render::asset_package::resolve_hmc_texture_resource(
878 &bundle, digest,
879 )
880 .map_err(|e| format!("HMC texture resolution: {e}"))?;
881
882 let (rgba8, _) = match qualia_core_db::render::texture_decode::decode_hmc_texture_rgba8(
884 &resource,
885 qualia_core_db::render::texture_decode::TextureDecodeLimits::default(),
886 ) {
887 Ok(decoded) => decoded,
888 Err(_) => {
889 for (_, _, mip_bytes, mip_count) in &selected {
890 note_refusal(&mut report, *mip_count, *mip_bytes);
891 }
892 continue;
893 }
894 };
895 for (entry, first_mip, mip_bytes, mip_count) in selected {
896 let upload = if first_mip == 0 {
897 renderer.inner.upload_resident_texture_rgba8_with_mips(
898 entry.digest,
899 entry.texture_use.color_space,
900 entry.texture_use.mip_semantic,
901 entry.width,
902 entry.height,
903 &rgba8,
904 )
905 } else {
906 let (coarse, cw, ch) = coarse_texture_level(
907 &rgba8,
908 entry.width,
909 entry.height,
910 first_mip,
911 entry.texture_use.mip_semantic,
912 )?;
913 if cw == 0 || ch == 0 {
914 return Err("HMC coarse texture dimensions are invalid".to_string());
915 }
916 renderer
917 .inner
918 .upload_resident_texture_rgba8_at_mip_with_mips(
919 entry.digest,
920 entry.texture_use.color_space,
921 entry.texture_use.mip_semantic,
922 entry.width,
923 entry.height,
924 u32::from(first_mip),
925 &coarse,
926 )
927 .map(|_| ())
928 };
929 match upload {
930 Ok(_) => {
931 newly_resident.push((entry.digest, entry.texture_use));
932 loaded_residency.insert(
933 (entry.digest, entry.texture_use),
934 (
935 first_mip,
936 rgba8_resident_bytes(entry.width, entry.height, first_mip)?,
937 ),
938 );
939 report.resident_interpretations += 1;
940 }
941 Err(TextureUploadError::GpuBudgetRefused)
942 | Err(TextureUploadError::UploadBudgetRefused) => {
943 note_refusal(&mut report, mip_count, mip_bytes);
944 }
945 Err(e) => return Err(format!("HMC texture upload: {e}")),
946 }
947 }
948 }
949 Ok(())
950 })();
951 if let Err(error) = upload_result {
952 for (digest, texture_use) in newly_resident {
953 renderer.inner.evict_resident_texture_with_mips(
954 &digest,
955 texture_use.color_space,
956 texture_use.mip_semantic,
957 );
958 }
959 return Err(error);
960 }
961 let mut all_plan_entries = plan_entries;
962 all_plan_entries.extend(ktx2_entries);
963 let stream_state = match build_texture_stream_state(
964 hmc_bytes,
965 asset_bytes,
966 &all_plan_entries,
967 &loaded_residency,
968 ) {
969 Ok(state) => state,
970 Err(error) => {
971 for (digest, texture_use) in newly_resident {
972 renderer.inner.evict_resident_texture_with_mips(
973 &digest,
974 texture_use.color_space,
975 texture_use.mip_semantic,
976 );
977 }
978 return Err(error);
979 }
980 };
981 match renderer.load_10d_asset(asset_bytes) {
982 Ok(result) => {
983 evict_replaced_asset_textures(renderer, &all_plan_entries);
984 renderer.texture_stream_state = Some(stream_state);
985 Ok((result, report))
986 }
987 Err(error) => {
988 for (digest, texture_use) in newly_resident {
989 renderer.inner.evict_resident_texture_with_mips(
990 &digest,
991 texture_use.color_space,
992 texture_use.mip_semantic,
993 );
994 }
995 Err(error)
996 }
997 }
998}
999
1000pub fn request_texture_stream(
1002 renderer: &super::VolumetricRenderer,
1003 request: HmcTextureStreamApplyRequest<'_>,
1004) -> Result<HmcTextureStreamPlan, String> {
1005 volumetric_hmc_stream::request_texture_stream(renderer, request)
1006}
1007
1008pub fn apply_texture_stream(
1010 renderer: &mut super::VolumetricRenderer,
1011 plan: HmcTextureStreamPlan,
1012) -> Result<(), String> {
1013 volumetric_hmc_stream::apply_texture_stream(renderer, plan)
1014}
1015
1016pub fn load_hmc_water_asset(
1020 renderer: &mut super::VolumetricRenderer,
1021 hmc_bytes: &[u8],
1022 asset_key: &str,
1023) -> Result<(u32, u32), String> {
1024 load_hmc_water_asset_with_policy(renderer, hmc_bytes, asset_key, HmcWaterLoadPolicy::default())
1025}
1026
1027pub fn load_hmc_water_asset_with_policy(
1030 renderer: &mut super::VolumetricRenderer,
1031 hmc_bytes: &[u8],
1032 asset_key: &str,
1033 policy: HmcWaterLoadPolicy,
1034) -> Result<(u32, u32), String> {
1035 let bundle = qualia_core_db::bundle::BundleReader::parse(hmc_bytes)
1036 .map_err(|e| format!("HMC bundle: {e}"))?;
1037 let asset_bytes = bundle
1038 .get(asset_key)
1039 .ok_or_else(|| format!("HMC asset is missing: {asset_key}"))?;
1040 if !bundle.verify_entry(asset_key) {
1041 return Err(format!("HMC asset digest check failed: {asset_key}"));
1042 }
1043 let entry = bundle
1044 .entry(asset_key)
1045 .ok_or_else(|| format!("HMC asset index entry is missing: {asset_key}"))?;
1046 if entry.kind != "10d" {
1047 return Err(format!(
1048 "HMC water asset {asset_key} has kind {:?}, expected 10d",
1049 entry.kind
1050 ));
1051 }
1052 let header = Container10dHeader::parse(asset_bytes).map_err(|e| format!("10d header: {e}"))?;
1053 if qualia_core_db::container_10d::compute_whole_file_crc32c(asset_bytes) != header.header_crc32c
1054 {
1055 return Err("10d whole-file integrity check failed".to_string());
1056 }
1057 let descs = qualia_core_db::container_10d::parse_section_table(asset_bytes, &header)
1058 .map_err(|e| format!("10d section table: {e}"))?;
1059 let descriptor = descs
1060 .iter()
1061 .find(|descriptor| descriptor.typ() == Some(SectionType::QuantizedMesh))
1062 .ok_or_else(|| "HMC water asset has no QuantizedMesh section".to_string())?;
1063 let start = descriptor.byte_offset as usize;
1064 let end = start
1065 .checked_add(descriptor.byte_length as usize)
1066 .filter(|&end| end <= asset_bytes.len())
1067 .ok_or_else(|| "HMC water mesh section is outside asset bytes".to_string())?;
1068 let mesh = decode_mesh_section(&asset_bytes[start..end])
1069 .map_err(|e| format!("10d water mesh decode: {e}"))?;
1070 let geometry_bytes = validate_hmc_water_geometry(
1071 &mesh.positions,
1072 &mesh.triangles,
1073 policy.max_geometry_bytes,
1074 )?;
1075 let mut indices = Vec::new();
1076 indices
1077 .try_reserve_exact(mesh.triangles.len().saturating_mul(3))
1078 .map_err(|_| "HMC water index staging allocation refused".to_string())?;
1079 for triangle in &mesh.triangles {
1080 indices.extend_from_slice(triangle);
1081 }
1082 let vertex_count = u32::try_from(mesh.positions.len())
1083 .map_err(|_| "HMC water vertex count exceeds u32".to_string())?;
1084 let triangle_count = u32::try_from(mesh.triangles.len())
1085 .map_err(|_| "HMC water triangle count exceeds u32".to_string())?;
1086 renderer
1087 .inner
1088 .upload_water_geometry_with_budget(&mesh.positions, &indices, policy.max_geometry_bytes)?;
1089 renderer.inner.set_water_quality(select_hmc_water_quality(
1090 mesh.triangles.len(),
1091 geometry_bytes,
1092 policy.preferred_quality,
1093 ));
1094 Ok((vertex_count, triangle_count))
1095}