Skip to main content

qualia_core_db/render/gpu/
texture_residency.rs

1//! Bounded RGBA8 texture residency with semantic GPU-generated mip chains.
2
3use super::texture_mips::AlphaCoverageDiagnostics;
4use super::PortalGpu;
5use std::collections::BTreeMap;
6
7pub(super) use etalon_render::texture_layout::TextureIdentity;
8#[cfg(test)]
9use etalon_render::texture_layout::{mip_chain_layout, mip_semantic_matches, validate_upload};
10pub use etalon_render::texture_layout::{TextureColorSpace, TextureUploadError};
11
12pub(super) type ResidentTexture =
13    etalon_render::texture_residency::ResidentTexture<crate::gpu_context::VramReservation<'static>>;
14
15#[cfg(test)]
16fn alpha_mip_scratch_bytes(width: u32, height: u32) -> Result<u64, TextureUploadError> {
17    u64::from(width)
18        .checked_mul(u64::from(height))
19        .and_then(|pixels| pixels.checked_mul(4))
20        .ok_or(TextureUploadError::ByteSizeOverflow)
21}
22
23impl PortalGpu {
24    /// Upload a decoded RGBA8 base level and generate a complete mip chain on the GPU.
25    ///
26    /// This compatibility entry uses sRGB colour mips for sRGB textures and linear-data mips for
27    /// linear textures. Use the semantic variant for normal maps so their mips are renormalized.
28    pub fn upload_resident_texture_rgba8(
29        &mut self,
30        source_digest: [u8; 32],
31        color_space: TextureColorSpace,
32        width: u32,
33        height: u32,
34        rgba8: &[u8],
35    ) -> Result<(), TextureUploadError> {
36        let mip_semantic = match color_space {
37            TextureColorSpace::Srgb => super::texture_mips::TextureMipSemantic::Color,
38            TextureColorSpace::Linear => super::texture_mips::TextureMipSemantic::LinearData,
39        };
40        self.upload_resident_texture_rgba8_with_mips(
41            source_digest,
42            color_space,
43            mip_semantic,
44            width,
45            height,
46            rgba8,
47        )
48    }
49
50    /// Upload with a semantic mip filter: linear-light colour, linear data, or renormalized normals.
51    pub fn upload_resident_texture_rgba8_with_mips(
52        &mut self,
53        source_digest: [u8; 32],
54        color_space: TextureColorSpace,
55        mip_semantic: super::texture_mips::TextureMipSemantic,
56        width: u32,
57        height: u32,
58        rgba8: &[u8],
59    ) -> Result<(), TextureUploadError> {
60        self.upload_resident_texture_rgba8_with_mips_and_diagnostics(
61            source_digest,
62            color_space,
63            mip_semantic,
64            width,
65            height,
66            rgba8,
67        )
68        .map(|_| ())
69    }
70
71    /// Upload a texture and return the bounded CPU prediction for alpha-mask mip coverage.
72    ///
73    /// `None` is returned for non-alpha mip semantics. Diagnostics are returned by value instead
74    /// of retained in the residency map, so long-lived metadata does not grow per texture.
75    pub fn upload_resident_texture_rgba8_with_mips_and_diagnostics(
76        &mut self,
77        source_digest: [u8; 32],
78        color_space: TextureColorSpace,
79        mip_semantic: super::texture_mips::TextureMipSemantic,
80        width: u32,
81        height: u32,
82        rgba8: &[u8],
83    ) -> Result<Option<AlphaCoverageDiagnostics>, TextureUploadError> {
84        etalon_render::texture_residency::upload_rgba8(
85            &self.device,
86            &self.queue,
87            &self.mip_generator,
88            &mut self.resident_textures,
89            source_digest,
90            color_space,
91            mip_semantic,
92            width,
93            height,
94            rgba8,
95            cfg!(test),
96            |class, bytes| {
97                let class = match class {
98                    etalon_render::texture_residency::TextureAllocation::TextureResidency => {
99                        crate::gpu_context::VramResourceClass::TextureResidency
100                    }
101                    etalon_render::texture_residency::TextureAllocation::UploadStaging => {
102                        crate::gpu_context::VramResourceClass::UploadStaging
103                    }
104                };
105                crate::gpu_context::global_vram_ledger()
106                    .try_reserve_graphics(class, bytes)
107                    .ok()
108            },
109        )
110    }
111
112    /// Borrow the resident view and shared default sampler for `(digest, colour-space)`.
113    pub fn resident_texture_binding(
114        &self,
115        source_digest: &[u8; 32],
116        color_space: TextureColorSpace,
117    ) -> Option<(&etalon::TextureView, &etalon::Sampler)> {
118        let mip_semantic = match color_space {
119            TextureColorSpace::Srgb => super::texture_mips::TextureMipSemantic::Color,
120            TextureColorSpace::Linear => super::texture_mips::TextureMipSemantic::LinearData,
121        };
122        self.resident_texture_binding_with_mips(source_digest, color_space, mip_semantic)
123    }
124
125    /// Binding for a resident texture with mips.
126    pub fn resident_texture_binding_with_mips(
127        &self,
128        source_digest: &[u8; 32],
129        color_space: TextureColorSpace,
130        mip_semantic: super::texture_mips::TextureMipSemantic,
131    ) -> Option<(&etalon::TextureView, &etalon::Sampler)> {
132        let key = TextureIdentity {
133            source_digest: *source_digest,
134            color_space,
135            mip_semantic,
136        };
137        self.resident_textures.get(&key).map(|resident| {
138            (
139                &resident.view,
140                self.material_texture_defaults
141                    .sampler(crate::container_10d::TextureSampler::GLTF_DEFAULT),
142            )
143        })
144    }
145
146    /// Evict one interpretation of a source image and release its resident-byte reservation.
147    pub fn evict_resident_texture(
148        &mut self,
149        source_digest: &[u8; 32],
150        color_space: TextureColorSpace,
151    ) -> bool {
152        let previous_len = self.resident_textures.len();
153        self.resident_textures.retain(|identity, _| {
154            identity.source_digest != *source_digest || identity.color_space != color_space
155        });
156        self.resident_textures.len() != previous_len
157    }
158
159    /// Evicts a resident texture with mips.
160    pub fn evict_resident_texture_with_mips(
161        &mut self,
162        source_digest: &[u8; 32],
163        color_space: TextureColorSpace,
164        mip_semantic: super::texture_mips::TextureMipSemantic,
165    ) -> bool {
166        self.resident_textures
167            .remove(&TextureIdentity {
168                source_digest: *source_digest,
169                color_space,
170                mip_semantic,
171            })
172            .is_some()
173    }
174}
175
176pub(super) type ResidentTextureMap = BTreeMap<TextureIdentity, ResidentTexture>;
177
178/// `resident_view`.
179pub(super) use etalon_render::texture_residency::resident_view;
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    #[test]
186    fn upload_admission_checks_dimensions_and_exact_rgba_bytes() {
187        assert_eq!(validate_upload(2, 3, 8, 24), Ok((24, 8)));
188        assert_eq!(
189            validate_upload(0, 3, 8, 24),
190            Err(TextureUploadError::InvalidDimensions)
191        );
192        assert_eq!(
193            validate_upload(9, 3, 8, 108),
194            Err(TextureUploadError::TextureDimensionLimit)
195        );
196        assert_eq!(
197            validate_upload(2, 3, 8, 23),
198            Err(TextureUploadError::InvalidRgba8Length)
199        );
200    }
201
202    #[test]
203    fn mip_chain_budget_covers_odd_edges_and_rejects_colour_space_mismatch() {
204        assert_eq!(mip_chain_layout(1, 1), Ok((1, 4)));
205        assert_eq!(mip_chain_layout(2, 2), Ok((2, 20)));
206        assert_eq!(mip_chain_layout(3, 1), Ok((2, 16)));
207        assert_eq!(mip_chain_layout(4, 4), Ok((3, 84)));
208        assert!(mip_semantic_matches(
209            TextureColorSpace::Srgb,
210            super::super::texture_mips::TextureMipSemantic::Color
211        ));
212        assert!(!mip_semantic_matches(
213            TextureColorSpace::Srgb,
214            super::super::texture_mips::TextureMipSemantic::Normal
215        ));
216        assert!(!mip_semantic_matches(
217            TextureColorSpace::Linear,
218            super::super::texture_mips::TextureMipSemantic::Color
219        ));
220        assert!(mip_semantic_matches(
221            TextureColorSpace::Srgb,
222            super::super::texture_mips::TextureMipSemantic::alpha_mask(0.37).unwrap()
223        ));
224        assert!(!mip_semantic_matches(
225            TextureColorSpace::Linear,
226            super::super::texture_mips::TextureMipSemantic::alpha_mask(0.37).unwrap()
227        ));
228        assert_eq!(alpha_mip_scratch_bytes(5, 3), Ok(60));
229    }
230}