prav_core/decoder/
graph.rs

1/// Static graph structure containing grid topology metadata.
2///
3/// This structure holds precomputed information about the lattice dimensions
4/// and memory layout. It enables efficient coordinate calculations during
5/// decoding without runtime division or modulo operations.
6///
7/// # Design Philosophy
8///
9/// Traditional graph representations store explicit adjacency lists. This decoder
10/// instead uses SWAR (SIMD Within A Register) bit operations for neighbor traversal,
11/// achieving 19-427x faster performance than lookup tables. The `StaticGraph` stores
12/// only the minimal metadata needed to support these operations.
13///
14/// # Memory Layout
15///
16/// Nodes are organized in 64-node blocks using Morton (Z-order) encoding.
17/// Within each block, nodes are arranged as an 8x8 grid. Blocks themselves
18/// are arranged in row-major order.
19///
20/// ```text
21/// Grid Layout (4x4 blocks = 32x32 nodes):
22/// +--------+--------+--------+--------+
23/// | Blk 0  | Blk 1  | Blk 2  | Blk 3  |  Row 0
24/// +--------+--------+--------+--------+
25/// | Blk 4  | Blk 5  | Blk 6  | Blk 7  |  Row 1
26/// +--------+--------+--------+--------+
27/// | Blk 8  | Blk 9  | Blk 10 | Blk 11 |  Row 2
28/// +--------+--------+--------+--------+
29/// | Blk 12 | Blk 13 | Blk 14 | Blk 15 |  Row 3
30/// +--------+--------+--------+--------+
31/// ```
32#[derive(Debug, Clone, Copy)]
33pub struct StaticGraph {
34    /// Width of the grid in nodes (not blocks).
35    pub width: usize,
36    /// Height of the grid in nodes (not blocks).
37    pub height: usize,
38    /// Depth of the grid for 3D codes (1 for 2D codes).
39    pub depth: usize,
40    /// Stride to move one position in X direction (always 1).
41    pub stride_x: usize,
42    /// Stride to move one position in Y direction (typically equals width).
43    pub stride_y: usize,
44    /// Stride to move one position in Z direction (typically equals width * height).
45    pub stride_z: usize,
46    /// Number of blocks per row of blocks.
47    pub blk_stride_y: usize,
48    /// Log2 of stride_y for fast division via bit shift.
49    pub shift_y: u32,
50    /// Log2 of stride_z for fast division via bit shift.
51    pub shift_z: u32,
52    /// Bitmask identifying nodes at the right edge of their 8-wide block row.
53    pub row_end_mask: u64,
54    /// Bitmask identifying nodes at the left edge of their 8-wide block row.
55    pub row_start_mask: u64,
56}
prav_core/decoder/graph.rs

prav_core/decoder/
graph.rs
