Skip to main content

webizen_render/
volumetric_hmc_stream.rs

1//! Generation-stamped HMC texture working-set planning and application.
2
3use crate::volumetric_texture::coarse_texture_level;
4use qualia_core_db::bundle::BundleReader;
5use qualia_core_db::render::gpu::{TextureColorSpace, TextureMipSemantic};
6use qualia_core_db::render::texture_ktx2::Ktx2Document;
7use qualia_core_db::render::texture_stream_policy::{
8    plan_texture_residency_lifecycle, TextureStreamBudget, TextureStreamDemand,
9    TextureStreamLifecycleAction, TextureStreamLifecycleActionKind,
10};
11use qualia_core_db::render::texture_streaming_plan::{
12    decode_rgba8_ktx2_mip_into, rgba8_ktx2_mip_candidate,
13};
14
15use super::{is_ktx2_mime, ktx2_backend_cost, TextureUse};
16
17pub(super) const HMC_TEXTURE_STREAM_STATE_MAX_BYTES: usize = 256 * 1024 * 1024;
18pub(super) const HMC_TEXTURE_STREAM_MAX_ENTRIES: usize = 1_048_576;
19const HMC_TEXTURE_STREAM_PREPARE_MAX_BYTES: usize = 256 * 1024 * 1024;
20
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub(super) struct HmcTextureStreamEntry {
23    pub(super) semantic_id: u64,
24    pub(super) digest: [u8; 32],
25    pub(super) texture_use: TextureUse,
26    pub(super) width: u32,
27    pub(super) height: u32,
28    pub(super) mip_count: u8,
29    pub(super) supported_mips: u32,
30    pub(super) resident_finest_mip: Option<u8>,
31    pub(super) resident_bytes: u64,
32}
33
34pub(crate) struct HmcTextureStreamState {
35    pub(super) bundle_bytes: Vec<u8>,
36    pub(super) asset_bytes: Vec<u8>,
37    pub(super) entries: Vec<HmcTextureStreamEntry>,
38    pub(super) generation: u64,
39}
40
41/// One member of the next texture working set. The request list is authoritative: entries not
42/// present in it are unrequested and are evicted by the apply step.
43#[derive(Clone, Copy, Debug, PartialEq, Eq)]
44pub struct HmcTextureResidencyRequest {
45    pub digest: [u8; 32],
46    pub color_space: TextureColorSpace,
47    pub mip_semantic: TextureMipSemantic,
48    pub projected_width: u32,
49    pub projected_height: u32,
50    pub importance: u16,
51    pub distance_key: u32,
52    pub last_used_frame: u64,
53    pub pinned: bool,
54    pub visible: bool,
55}
56
57/// A complete working-set request for a previously loaded HMC asset.
58pub struct HmcTextureStreamApplyRequest<'a> {
59    pub budget: TextureStreamBudget,
60    pub requests: &'a [HmcTextureResidencyRequest],
61}
62
63/// A generation-stamped, caller-requested texture transition plan. It is intentionally separate
64/// from the renderer so a stale plan cannot mutate a newer asset generation.
65#[derive(Clone)]
66pub struct HmcTextureStreamPlan {
67    pub generation: u64,
68    pub action_count: usize,
69    pub admitted_count: usize,
70    pub deferred_count: usize,
71    pub admitted_upload_bytes: u64,
72    pub deferred_upload_bytes: u64,
73    pub projected_resident_bytes: u64,
74    state_fingerprint: u64,
75    actions: Vec<TextureStreamLifecycleAction>,
76}
77
78/// Build a generation-stamped lifecycle plan for the currently loaded HMC asset.
79///
80/// The selector slice is the complete requested working set. Omitting an entry is intentional and
81/// causes it to be evicted. Planning is read-only; GPU resources and material bindings change only
82/// in [`apply_texture_stream`].
83pub fn request_texture_stream(
84    renderer: &super::super::VolumetricRenderer,
85    request: HmcTextureStreamApplyRequest<'_>,
86) -> Result<HmcTextureStreamPlan, String> {
87    let state = renderer
88        .texture_stream_state
89        .as_ref()
90        .ok_or_else(|| "no HMC texture stream state is active".to_string())?;
91
92    for (index, selector) in request.requests.iter().enumerate() {
93        if request.requests[..index].iter().any(|previous| {
94            previous.digest == selector.digest
95                && previous.color_space == selector.color_space
96                && previous.mip_semantic == selector.mip_semantic
97        }) {
98            return Err("duplicate HMC texture stream selector".to_string());
99        }
100        if !state.entries.iter().any(|entry| {
101            entry.digest == selector.digest
102                && entry.texture_use.color_space == selector.color_space
103                && entry.texture_use.mip_semantic == selector.mip_semantic
104        }) {
105            return Err(
106                "HMC texture stream selector has no capability-admitted resident interpretation; \
107                 unsupported compressed/Basis data remains on the typed material fallback"
108                    .to_string(),
109            );
110        }
111    }
112
113    let mut demands = Vec::new();
114    demands
115        .try_reserve_exact(state.entries.len())
116        .map_err(|_| "HMC texture stream demand allocation refused".to_string())?;
117    for entry in &state.entries {
118        let selector = request.requests.iter().find(|selector| {
119            selector.digest == entry.digest
120                && selector.color_space == entry.texture_use.color_space
121                && selector.mip_semantic == entry.texture_use.mip_semantic
122        });
123        let requested = selector.is_some();
124        let (desired_finest_mip, pinned, visible, importance, distance_key, last_used_frame) =
125            if let Some(selector) = selector {
126                let requested_mip = desired_stream_mip(
127                    entry.width,
128                    entry.height,
129                    entry.mip_count,
130                    selector.projected_width,
131                    selector.projected_height,
132                );
133                (
134                    select_capability_mip(*entry, requested_mip).ok_or_else(|| {
135                        format!(
136                            "HMC texture capability refusal for {:?}: no authored RGBA8 mip \
137                             can satisfy the requested footprint; typed material fallback remains \
138                             active",
139                            entry.texture_use
140                        )
141                    })?,
142                    selector.pinned,
143                    selector.visible,
144                    selector.importance,
145                    selector.distance_key,
146                    selector.last_used_frame,
147                )
148            } else {
149                (
150                    entry.resident_finest_mip.unwrap_or(entry.mip_count.saturating_sub(1)),
151                    false,
152                    false,
153                    0,
154                    u32::MAX,
155                    0,
156                )
157            };
158        demands.push(TextureStreamDemand {
159            semantic_id: entry.semantic_id,
160            width: entry.width,
161            height: entry.height,
162            mip_count: entry.mip_count,
163            block_width: 1,
164            block_height: 1,
165            bytes_per_block: 4,
166            desired_finest_mip,
167            resident_finest_mip: entry.resident_finest_mip,
168            resident_bytes: entry.resident_bytes,
169            requested,
170            pinned,
171            visible: requested && visible,
172            importance,
173            distance_key,
174            last_used_frame,
175        });
176    }
177
178    let mut actions = Vec::new();
179    actions
180        .try_reserve_exact(state.entries.len())
181        .map_err(|_| "HMC texture stream action allocation refused".to_string())?;
182    actions.resize(
183        state.entries.len(),
184        TextureStreamLifecycleAction {
185            semantic_id: 0,
186            kind: TextureStreamLifecycleActionKind::EvictTexture,
187            mip_level: 0,
188            bytes: 0,
189            previous_resident_bytes: 0,
190            target_resident_bytes: 0,
191        },
192    );
193    let lifecycle = plan_texture_residency_lifecycle(
194        &demands,
195        request.budget,
196        state.generation,
197        &mut actions,
198    )
199    .map_err(|error| format!("HMC texture lifecycle plan: {error:?}"))?;
200    actions.truncate(lifecycle.action_count);
201
202    Ok(HmcTextureStreamPlan {
203        generation: lifecycle.generation,
204        action_count: lifecycle.action_count,
205        admitted_count: lifecycle.admitted_count,
206        deferred_count: lifecycle.deferred_count,
207        admitted_upload_bytes: lifecycle.admitted_upload_bytes,
208        deferred_upload_bytes: lifecycle.deferred_upload_bytes,
209        projected_resident_bytes: lifecycle.projected_resident_bytes,
210        state_fingerprint: stream_state_fingerprint(state),
211        actions,
212    })
213}
214
215fn stream_state_fingerprint(state: &HmcTextureStreamState) -> u64 {
216    // This is an identity stamp, not a security digest. It prevents a plan from asset A from
217    // being applied to a newly loaded asset B whose lifecycle generation also starts at zero.
218    let mut fingerprint = 0xcbf29ce484222325u64;
219    for byte in state.bundle_bytes.iter().chain(&state.asset_bytes) {
220        fingerprint ^= u64::from(*byte);
221        fingerprint = fingerprint.wrapping_mul(0x100000001b3);
222    }
223    for entry in &state.entries {
224        fingerprint ^= entry.semantic_id;
225        fingerprint = fingerprint.wrapping_mul(0x100000001b3);
226        for byte in entry.digest {
227            fingerprint ^= u64::from(byte);
228            fingerprint = fingerprint.wrapping_mul(0x100000001b3);
229        }
230    }
231    fingerprint
232}
233
234fn mip_is_supported(entry: HmcTextureStreamEntry, mip_level: u8) -> bool {
235    mip_level < entry.mip_count
236        && mip_level < u32::BITS as u8
237        && (entry.supported_mips & (1u32 << u32::from(mip_level))) != 0
238}
239
240/// Pick the closest authored capability to the requested footprint. Finer authored levels are
241/// preferred when no adequate coarse level exists; otherwise the closest coarser level is used.
242/// This makes a sparse authored chain a quality fallback rather than a lifecycle failure.
243fn select_capability_mip(entry: HmcTextureStreamEntry, requested_mip: u8) -> Option<u8> {
244    if entry.mip_count == 0 || entry.mip_count > u32::BITS as u8 {
245        return None;
246    }
247    let requested_mip = requested_mip.min(entry.mip_count - 1);
248    for mip_level in (0..=requested_mip).rev() {
249        if mip_is_supported(entry, mip_level) {
250            return Some(mip_level);
251        }
252    }
253    for mip_level in requested_mip.saturating_add(1)..entry.mip_count {
254        if mip_is_supported(entry, mip_level) {
255            return Some(mip_level);
256        }
257    }
258    None
259}
260
261fn desired_stream_mip(
262    width: u32,
263    height: u32,
264    mip_count: u8,
265    projected_width: u32,
266    projected_height: u32,
267) -> u8 {
268    if projected_width == 0 || projected_height == 0 {
269        return 0;
270    }
271    let mut level = 0u8;
272    while level + 1 < mip_count {
273        let next_width = (width >> u32::from(level + 1)).max(1);
274        let next_height = (height >> u32::from(level + 1)).max(1);
275        if next_width >= projected_width && next_height >= projected_height {
276            level += 1;
277        } else {
278            break;
279        }
280    }
281    level
282}
283
284fn rgba8_mip_bytes(entry: HmcTextureStreamEntry, mip_level: u8) -> Result<u64, String> {
285    if mip_level >= entry.mip_count {
286        return Err("HMC texture lifecycle mip is outside the authored range".to_string());
287    }
288    let width = entry
289        .width
290        .checked_shr(u32::from(mip_level))
291        .unwrap_or(0)
292        .max(1);
293    let height = entry
294        .height
295        .checked_shr(u32::from(mip_level))
296        .unwrap_or(0)
297        .max(1);
298    u64::from(width)
299        .checked_mul(u64::from(height))
300        .and_then(|pixels| pixels.checked_mul(4))
301        .ok_or_else(|| "HMC texture lifecycle mip byte size overflow".to_string())
302}
303
304fn rgba8_resident_bytes(entry: HmcTextureStreamEntry, first_mip: u8) -> Result<u64, String> {
305    if first_mip >= entry.mip_count {
306        return Err("HMC texture lifecycle resident mip is outside the authored range".to_string());
307    }
308    let mut total = 0u64;
309    for mip_level in first_mip..entry.mip_count {
310        total = total
311            .checked_add(rgba8_mip_bytes(entry, mip_level)?)
312            .ok_or_else(|| "HMC texture lifecycle resident byte size overflow".to_string())?;
313    }
314    Ok(total)
315}
316
317fn validate_lifecycle_action(
318    action: TextureStreamLifecycleAction,
319    entry: HmcTextureStreamEntry,
320) -> Result<(), String> {
321    match action.kind {
322        TextureStreamLifecycleActionKind::EvictTexture => {
323            if entry.resident_finest_mip.is_none()
324                || action.mip_level != 0
325                || action.bytes != 0
326                || action.previous_resident_bytes != entry.resident_bytes
327                || action.target_resident_bytes != 0
328            {
329                return Err("invalid HMC texture eviction transition".to_string());
330            }
331        }
332        TextureStreamLifecycleActionKind::UploadTexture
333        | TextureStreamLifecycleActionKind::ReplaceTexture => {
334            if !mip_is_supported(entry, action.mip_level)
335                || action.bytes != rgba8_mip_bytes(entry, action.mip_level)?
336                || action.target_resident_bytes != rgba8_resident_bytes(entry, action.mip_level)?
337                || action.previous_resident_bytes != entry.resident_bytes
338            {
339                return Err(
340                    "invalid HMC texture upload transition or unsupported authored mip".to_string(),
341                );
342            }
343            let expected_kind = if entry.resident_finest_mip.is_some() {
344                TextureStreamLifecycleActionKind::ReplaceTexture
345            } else {
346                TextureStreamLifecycleActionKind::UploadTexture
347            };
348            if action.kind != expected_kind {
349                return Err(
350                    "HMC texture lifecycle transition kind does not match residency".to_string(),
351                );
352            }
353        }
354    }
355    Ok(())
356}
357
358struct PreparedTextureTransition {
359    action: TextureStreamLifecycleAction,
360    entry: HmcTextureStreamEntry,
361    new_bytes: Option<Vec<u8>>,
362    old_bytes: Option<Vec<u8>>,
363}
364
365fn prepare_texture_upload(
366    bundle: &BundleReader<'_>,
367    entry: HmcTextureStreamEntry,
368    mip_level: u8,
369) -> Result<Vec<u8>, String> {
370    if !mip_is_supported(entry, mip_level) {
371        return Err(
372            "HMC texture capability refusal: authored compressed/Basis mip is unsupported; \
373             the material remains on the typed fallback"
374                .to_string(),
375        );
376    }
377    let resource = qualia_core_db::render::asset_package::resolve_hmc_texture_resource(
378        bundle,
379        &entry.digest,
380    )
381    .map_err(|error| format!("HMC texture resolution: {error}"))?;
382    if is_ktx2_mime(resource.mime_type) {
383        let document = Ktx2Document::parse(resource.bytes)
384            .map_err(|_| {
385                "HMC texture capability refusal: invalid or Basis-compressed KTX2; \
386                 the material remains on the typed fallback"
387                    .to_string()
388            })?;
389        let candidate = rgba8_ktx2_mip_candidate(
390            &document,
391            usize::from(mip_level),
392            ktx2_backend_cost(&document, usize::from(mip_level))
393                .map_err(|error| format!("HMC texture capability refusal: {error:?}"))?,
394        )
395        .map_err(|error| {
396            format!(
397                "HMC texture capability refusal: {error:?}; unsupported compressed/Basis data \
398                 remains on the typed material fallback"
399            )
400        })?;
401        if (entry.texture_use.color_space == TextureColorSpace::Srgb) != candidate.is_srgb {
402            return Err("HMC texture capability refusal: colour-space mismatch".to_string());
403        }
404        let length = usize::try_from(candidate.decoded_cpu_bytes)
405            .map_err(|_| "HMC texture upload size exceeds usize".to_string())?;
406        let mut bytes = Vec::new();
407        bytes
408            .try_reserve_exact(length)
409            .map_err(|_| "HMC texture upload allocation refused".to_string())?;
410        bytes.resize(length, 0);
411        decode_rgba8_ktx2_mip_into(&document, usize::from(mip_level), &mut bytes)
412            .map_err(|error| format!("HMC KTX2 decode: {error:?}"))?;
413        return Ok(bytes);
414    }
415
416    let (rgba8, _) = qualia_core_db::render::texture_decode::decode_hmc_texture_rgba8(
417        &resource,
418        qualia_core_db::render::texture_decode::TextureDecodeLimits::default(),
419    )
420    .map_err(|error| {
421        format!(
422            "HMC texture capability refusal: {error:?}; material remains on the typed fallback"
423        )
424    })?;
425    if mip_level == 0 {
426        return Ok(rgba8);
427    }
428    let (coarse, width, height) = coarse_texture_level(
429        &rgba8,
430        entry.width,
431        entry.height,
432        mip_level,
433        entry.texture_use.mip_semantic,
434    )?;
435    let expected = usize::try_from(
436        u64::from(width)
437            .checked_mul(u64::from(height))
438            .and_then(|pixels| pixels.checked_mul(4))
439            .ok_or_else(|| "HMC texture coarse byte size overflow".to_string())?,
440    )
441    .map_err(|_| "HMC texture coarse byte size exceeds usize".to_string())?;
442    if coarse.len() != expected {
443        return Err("HMC texture coarse decode length mismatch".to_string());
444    }
445    Ok(coarse)
446}
447
448/// Apply a plan atomically with respect to the renderer's logical state and material bindings.
449/// Existing resources are retained as rollback payloads until every replacement and the material
450/// rebind succeed. The GPU ledger is charged only by the actual upload calls; the plan itself is
451/// accounting, so a refinement cannot debit the same allocation twice.
452pub fn apply_texture_stream(
453    renderer: &mut super::super::VolumetricRenderer,
454    plan: HmcTextureStreamPlan,
455) -> Result<(), String> {
456    // Detach the state for the transaction. This keeps the retained bundle/asset bytes borrowed
457    // throughout preparation and avoids cloning the entire HMC state on every refinement frame.
458    let Some(mut state) = renderer.texture_stream_state.take() else {
459        return Err("no HMC texture stream state is active".to_string());
460    };
461    if state.generation != plan.generation {
462        let error = format!(
463            "stale HMC texture stream plan: {} != {}",
464            plan.generation, state.generation
465        );
466        renderer.texture_stream_state = Some(state);
467        return Err(error);
468    }
469    if stream_state_fingerprint(&state) != plan.state_fingerprint {
470        renderer.texture_stream_state = Some(state);
471        return Err("stale HMC texture stream plan: asset identity changed".to_string());
472    }
473    let next_generation = match state.generation.checked_add(1) {
474        Some(generation) => generation,
475        None => {
476            renderer.texture_stream_state = Some(state);
477            return Err("HMC texture stream generation overflow".to_string());
478        }
479    };
480    let bundle = match BundleReader::parse(&state.bundle_bytes) {
481        Ok(bundle) => bundle,
482        Err(error) => {
483            renderer.texture_stream_state = Some(state);
484            return Err(format!("HMC texture stream bundle: {error}"));
485        }
486    };
487
488    if plan.action_count != plan.actions.len() {
489        renderer.texture_stream_state = Some(state);
490        return Err("HMC texture stream plan action count is inconsistent".to_string());
491    }
492
493    let mut transitions = Vec::new();
494    let mut prepared_bytes = 0usize;
495    if transitions
496        .try_reserve_exact(plan.actions.len())
497        .is_err()
498    {
499        renderer.texture_stream_state = Some(state);
500        return Err("HMC texture transition allocation refused".to_string());
501    }
502    for action in &plan.actions {
503        if plan.actions[..transitions.len()].iter().any(|previous| {
504            previous.semantic_id == action.semantic_id
505        }) {
506            renderer.texture_stream_state = Some(state);
507            return Err(
508                "HMC texture lifecycle plan contains duplicate resource transitions".to_string(),
509            );
510        }
511        let entry = state
512            .entries
513            .iter()
514            .find(|entry| entry.semantic_id == action.semantic_id)
515            .copied()
516            .ok_or_else(|| "HMC texture lifecycle action references unknown resource".to_string());
517        let entry = match entry {
518            Ok(entry) => entry,
519            Err(error) => {
520                renderer.texture_stream_state = Some(state);
521                return Err(error);
522            }
523        };
524        if let Err(error) = validate_lifecycle_action(*action, entry) {
525            renderer.texture_stream_state = Some(state);
526            return Err(error);
527        }
528        let new_bytes = match action.kind {
529            TextureStreamLifecycleActionKind::EvictTexture => None,
530            TextureStreamLifecycleActionKind::UploadTexture
531            | TextureStreamLifecycleActionKind::ReplaceTexture => Some(prepare_texture_upload(
532                &bundle,
533                entry,
534                action.mip_level,
535            )),
536        };
537        let new_bytes = match new_bytes {
538            Some(result) => match result {
539                Ok(bytes) => Some(bytes),
540                Err(error) => {
541                    renderer.texture_stream_state = Some(state);
542                    return Err(error);
543                }
544            },
545            None => None,
546        };
547        let old_bytes = if entry.resident_finest_mip.is_some() {
548            Some(prepare_texture_upload(
549                &bundle,
550                entry,
551                entry.resident_finest_mip.unwrap_or(0),
552            ))
553        } else {
554            None
555        };
556        let old_bytes = match old_bytes {
557            Some(result) => match result {
558                Ok(bytes) => Some(bytes),
559                Err(error) => {
560                    renderer.texture_stream_state = Some(state);
561                    return Err(error);
562                }
563            },
564            None => None,
565        };
566        let Some(next_prepared_bytes) = prepared_bytes
567            .checked_add(new_bytes.as_ref().map_or(0, |bytes| bytes.len()))
568            .and_then(|bytes| {
569                bytes.checked_add(old_bytes.as_ref().map_or(0, |old_bytes| old_bytes.len()))
570            })
571        else {
572            renderer.texture_stream_state = Some(state);
573            return Err("HMC texture transition staging size overflow".to_string());
574        };
575        prepared_bytes = next_prepared_bytes;
576        if prepared_bytes > HMC_TEXTURE_STREAM_PREPARE_MAX_BYTES {
577            let error = format!(
578                "HMC texture transition staging exceeds bounded limit: {} > {} bytes",
579                prepared_bytes, HMC_TEXTURE_STREAM_PREPARE_MAX_BYTES
580            );
581            renderer.texture_stream_state = Some(state);
582            return Err(error);
583        }
584        transitions.push(PreparedTextureTransition {
585            action: *action,
586            entry,
587            new_bytes,
588            old_bytes,
589        });
590    }
591
592    if transitions.is_empty() {
593        state.generation = next_generation;
594        renderer.texture_stream_state = Some(state);
595        return Ok(());
596    }
597
598    for transition in &transitions {
599        renderer.inner.evict_resident_texture_with_mips(
600            &transition.entry.digest,
601            transition.entry.texture_use.color_space,
602            transition.entry.texture_use.mip_semantic,
603        );
604    }
605    for transition in &transitions {
606        let Some(bytes) = transition.new_bytes.as_deref() else {
607            continue;
608        };
609        if let Err(error) = renderer
610            .inner
611            .upload_resident_texture_rgba8_at_mip_with_mips(
612                transition.entry.digest,
613                transition.entry.texture_use.color_space,
614                transition.entry.texture_use.mip_semantic,
615                transition.entry.width,
616                transition.entry.height,
617                u32::from(transition.action.mip_level),
618                bytes,
619            )
620        {
621            let rollback = rollback_texture_transitions(renderer, &transitions);
622            let result = match rollback {
623                Ok(()) => format!("HMC texture stream upload failed: {error}"),
624                Err(rollback) => format!(
625                    "HMC texture stream upload failed: {error}; rollback failed: {rollback}"
626                ),
627            };
628            renderer.texture_stream_state = Some(state);
629            return Err(result);
630        }
631    }
632
633    if let Err(error) = renderer.load_10d_asset(&state.asset_bytes) {
634        let rollback = rollback_texture_transitions(renderer, &transitions);
635        let rebind = renderer.load_10d_asset(&state.asset_bytes);
636        let result = match (rollback, rebind) {
637            (Ok(()), Ok(_)) => format!("HMC material rebind failed: {error}"),
638            (Err(rollback), Ok(_)) => format!(
639                "HMC material rebind failed: {error}; rollback failed: {rollback}"
640            ),
641            (Ok(()), Err(rebind)) => format!(
642                "HMC material rebind failed: {error}; restoring previous material bindings failed: \
643                 {rebind}"
644            ),
645            (Err(rollback), Err(rebind)) => format!(
646                "HMC material rebind failed: {error}; rollback failed: {rollback}; \
647                 restoring previous material bindings failed: {rebind}"
648            ),
649        };
650        renderer.texture_stream_state = Some(state);
651        return Err(result);
652    }
653
654    for transition in &transitions {
655        if let Some(entry) = state
656            .entries
657            .iter_mut()
658            .find(|entry| entry.semantic_id == transition.action.semantic_id)
659        {
660            match transition.action.kind {
661                TextureStreamLifecycleActionKind::EvictTexture => {
662                    entry.resident_finest_mip = None;
663                    entry.resident_bytes = 0;
664                }
665                TextureStreamLifecycleActionKind::UploadTexture
666                | TextureStreamLifecycleActionKind::ReplaceTexture => {
667                    entry.resident_finest_mip = Some(transition.action.mip_level);
668                    entry.resident_bytes = transition.action.target_resident_bytes;
669                }
670            }
671        }
672    }
673    state.generation = next_generation;
674    renderer.texture_stream_state = Some(state);
675    Ok(())
676}
677
678fn rollback_texture_transitions(
679    renderer: &mut super::super::VolumetricRenderer,
680    transitions: &[PreparedTextureTransition],
681) -> Result<(), String> {
682    for transition in transitions {
683        renderer.inner.evict_resident_texture_with_mips(
684            &transition.entry.digest,
685            transition.entry.texture_use.color_space,
686            transition.entry.texture_use.mip_semantic,
687        );
688    }
689    for transition in transitions {
690        let Some(bytes) = transition.old_bytes.as_deref() else {
691            continue;
692        };
693        renderer
694            .inner
695            .upload_resident_texture_rgba8_at_mip_with_mips(
696                transition.entry.digest,
697                transition.entry.texture_use.color_space,
698                transition.entry.texture_use.mip_semantic,
699                transition.entry.width,
700                transition.entry.height,
701                u32::from(transition.entry.resident_finest_mip.unwrap_or(0)),
702                bytes,
703            )
704            .map_err(|error| format!("{error}"))?;
705    }
706    Ok(())
707}
708
709#[cfg(test)]
710mod tests {
711    use super::*;
712
713    fn entry(supported_mips: u32) -> HmcTextureStreamEntry {
714        HmcTextureStreamEntry {
715            semantic_id: 1,
716            digest: [7; 32],
717            texture_use: TextureUse {
718                color_space: TextureColorSpace::Srgb,
719                mip_semantic: TextureMipSemantic::Color,
720            },
721            width: 16,
722            height: 16,
723            mip_count: 5,
724            supported_mips,
725            resident_finest_mip: None,
726            resident_bytes: 0,
727        }
728    }
729
730    #[test]
731    fn capability_selection_prefers_nearest_supported_quality() {
732        let entry = entry((1 << 0) | (1 << 2));
733        assert_eq!(select_capability_mip(entry, 2), Some(2));
734        assert_eq!(select_capability_mip(entry, 1), Some(0));
735        assert_eq!(select_capability_mip(entry, 3), Some(2));
736    }
737
738    #[test]
739    fn capability_selection_refuses_an_empty_authored_chain() {
740        assert_eq!(select_capability_mip(entry(0), 0), None);
741    }
742
743    #[test]
744    fn lifecycle_bytes_match_the_physical_generated_tail() {
745        let entry = entry(0b1_1111);
746        assert_eq!(rgba8_mip_bytes(entry, 1), Ok(256));
747        assert_eq!(rgba8_resident_bytes(entry, 1), Ok(340));
748    }
749
750    #[test]
751    fn asset_identity_stamp_changes_when_a_new_asset_reuses_generation_zero() {
752        let entry = entry(0b1_1111);
753        let first = HmcTextureStreamState {
754            bundle_bytes: vec![1],
755            asset_bytes: vec![2],
756            entries: vec![entry],
757            generation: 0,
758        };
759        let mut second = HmcTextureStreamState {
760            bundle_bytes: first.bundle_bytes.clone(),
761            asset_bytes: first.asset_bytes.clone(),
762            entries: first.entries.clone(),
763            generation: 0,
764        };
765        second.asset_bytes[0] = 3;
766        assert_ne!(stream_state_fingerprint(&first), stream_state_fingerprint(&second));
767    }
768}