Skip to main content

qualia_geospatial/
wms_streamer.rs

1//! Satellite Imagery & Visual Map Drape Streamer (WMS / WMTS Display Path).
2//!
3//! Manages tile-matrix addressing ($z, x, y$) and caches $256 \times 256$ RGBA8 textures
4//! into slices of a GPU 2D Texture Array without scraping physical truth from pixels.
5
6pub const TILE_DIMENSION_PX: usize = 256;
7pub const TILE_BYTES: usize = TILE_DIMENSION_PX * TILE_DIMENSION_PX * 4; // 256 KB per slice
8pub const MAX_CACHE_LAYERS: usize = 32; // 32-layer 2D Texture Array (8 MB VRAM footprint)
9
10/// Tile coordinate in standard Slippy Map / WMTS tile-matrix convention ($z, x, y$).
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
12pub struct TileCoordinate {
13    pub zoom: u8,
14    pub x: u32,
15    pub y: u32,
16}
17
18/// A cached texture slice entry in the GPU 2D Texture Array.
19#[derive(Debug, Clone, Copy, PartialEq)]
20pub struct TextureArraySlot {
21    pub coord: TileCoordinate,
22    pub layer_index: u32,
23    pub last_accessed_frame: u64,
24    pub is_valid: bool,
25}
26
27/// WMS / WMTS Tile Array Cache Manager.
28pub struct WmsTileStreamer {
29    pub slots: [TextureArraySlot; MAX_CACHE_LAYERS],
30    pub current_frame: u64,
31}
32
33impl Default for WmsTileStreamer {
34    fn default() -> Self {
35        let dummy = TextureArraySlot {
36            coord: TileCoordinate { zoom: 0, x: 0, y: 0 },
37            layer_index: 0,
38            last_accessed_frame: 0,
39            is_valid: false,
40        };
41        let mut slots = [dummy; MAX_CACHE_LAYERS];
42        for i in 0..MAX_CACHE_LAYERS {
43            slots[i].layer_index = i as u32;
44        }
45        Self {
46            slots,
47            current_frame: 0,
48        }
49    }
50}
51
52impl WmsTileStreamer {
53    /// Advances frame counter for LRU eviction.
54    #[inline]
55    pub fn advance_frame(&mut self) {
56        self.current_frame = self.current_frame.wrapping_add(1);
57    }
58
59    /// Looks up a tile in the cache; returns layer slice index in the GPU 2D Texture Array.
60    pub fn lookup_tile(&mut self, coord: &TileCoordinate) -> Option<u32> {
61        for slot in &mut self.slots {
62            if slot.is_valid && slot.coord == *coord {
63                slot.last_accessed_frame = self.current_frame;
64                return Some(slot.layer_index);
65            }
66        }
67        None
68    }
69
70    /// Allocates or evicts a slot for a newly fetched tile coordinate.
71    pub fn allocate_slot(&mut self, coord: &TileCoordinate) -> u32 {
72        // 1. Check if already present
73        if let Some(idx) = self.lookup_tile(coord) {
74            return idx;
75        }
76
77        // 2. Find unused slot
78        for slot in &mut self.slots {
79            if !slot.is_valid {
80                slot.coord = *coord;
81                slot.last_accessed_frame = self.current_frame;
82                slot.is_valid = true;
83                return slot.layer_index;
84            }
85        }
86
87        // 3. Evict least-recently-used slot
88        let mut lru_idx = 0;
89        let mut oldest_frame = u64::MAX;
90        for (i, slot) in self.slots.iter().enumerate() {
91            if slot.last_accessed_frame < oldest_frame {
92                oldest_frame = slot.last_accessed_frame;
93                lru_idx = i;
94            }
95        }
96
97        self.slots[lru_idx].coord = *coord;
98        self.slots[lru_idx].last_accessed_frame = self.current_frame;
99        self.slots[lru_idx].is_valid = true;
100        self.slots[lru_idx].layer_index
101    }
102}