Skip to main content

webizen_render/
volumetric_hmc.rs

1//! HMC asset and texture streaming admission for the volumetric renderer.
2
3use 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/// Request-bearing parameters for texture streaming and view-footprint selection.
181#[derive(Clone, Copy, Debug, Eq, PartialEq)]
182pub struct HmcTextureStreamRequest {
183    pub budget: TextureStreamBudget,
184    /// Projected on-screen sampling footprint width (0 = unconstrained, finest authored).
185    pub projected_width: u32,
186    /// Projected on-screen sampling footprint height (0 = unconstrained, finest authored).
187    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
203/// `true` when ktx2-mime.
204pub(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/// Admission and presentation policy for a persistent HMC water surface.
216/// Geometry admission is independent from texture fallback: a refused water
217/// surface must never evict or replace an already resident surface.
218#[derive(Clone, Copy, Debug, PartialEq, Eq)]
219pub struct HmcWaterLoadPolicy {
220    pub max_geometry_bytes: u64,
221    /// 0 = lower tier, 1 = balanced, 2 = cinematic bounded response.
222    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
234/// Validates hmc-water-geometry.
235pub(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
272/// Selects hmc-water-quality.
273pub(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    // Larger surfaces retain authoritative depth and stable normals but use
283    // the lower-cost bounded reflection/foam response.
284    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
508/// Load an HMC `.10d` asset while admitting texture mips according to footprint and budget.
509pub 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        // KTX2 resources are admitted from their indexed authored levels. Do not route them
570        // through the generic image inspector: that inspector intentionally validates level zero,
571        // while coarse-first streaming must be able to start from a later valid level.
572        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        // KTX2 uses the indexed-level planner directly. This keeps the selected authored level
754        // independent of the generic coarse-prefix policy and, importantly, makes the decode
755        // operate on only the level that was admitted by footprint and budget.
756        // The indexed-level planner shares the same per-load budgets as the legacy image path.
757        // Account for already-admitted non-KTX2 requests before selecting any KTX2 level so a
758        // mixed asset cannot independently spend the full budget twice.
759        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            // Fallback: Full base decode + CPU downsample for PNG and JPEG.
883            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
1000/// Requests a texture stream.
1001pub 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
1008/// Applies texture-stream.
1009pub 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
1016/// Load an HMC `.10d` geometry asset into the renderer's persistent water
1017/// surface slot. Water is presentation-only: it shares the renderer model
1018/// transform and scene depth, but does not become a pickable/entity mesh.
1019pub 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
1027/// Policy-bearing HMC water load. Validation and admission happen before any
1028/// GPU replacement, so failed loads leave the previous water surface intact.
1029pub 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}