mlt_core/decoder/stream/
model.rs

1use derive_debug::Dbg;
2use num_enum::TryFromPrimitive;
3
4use crate::utils::formatter::{bytes_dbg, compact_dbg};
5use crate::{MltError, MltResult};
6
7/// Logical encoding technique used for a column, as stored in the tile
8#[derive(Debug, Clone, Copy, PartialEq, TryFromPrimitive)]
9#[repr(u8)]
10pub enum LogicalTechnique {
11    None = 0,
12    Delta = 1,
13    ComponentwiseDelta = 2,
14    Rle = 3,
15    Morton = 4,
16    PseudoDecimal = 5,
17}
18
19/// Metadata for RLE decoding
20/// TODO v2 optimizations:
21///   * runs is identical to half the size of the associated array
22///   * `num_rle_values` is identical to the size of the sum of the first half of the array.
23///     Computing checked sum should not be too expensive.
24#[derive(Debug, Clone, Copy, PartialEq)]
25pub struct RleMeta {
26    pub(crate) runs: u32,
27    pub(crate) num_rle_values: u32,
28}
29
30/// Metadata for Morton decoding
31#[derive(Debug, Clone, Copy, PartialEq)]
32pub struct Morton {
33    /// Number of bits used
34    pub(crate) bits: u32,
35    /// Coordinate shift
36    pub(crate) shift: u32,
37}
38
39impl Morton {
40    pub fn new(bits: u32, shift: u32) -> MltResult<Self> {
41        if bits <= 16 {
42            Ok(Self { bits, shift })
43        } else {
44            Err(MltError::InvalidMortonBits(bits))
45        }
46    }
47}
48
49/// How should the stream be interpreted at the logical level (second pass of decoding)
50#[derive(Debug, Clone, Copy, PartialEq)]
51pub enum LogicalEncoding {
52    None,
53    Delta,
54    DeltaRle(RleMeta),
55    ComponentwiseDelta,
56    Rle(RleMeta),
57    Morton(Morton),
58    MortonDelta(Morton),
59    MortonRle(Morton),
60    PseudoDecimal,
61}
62
63/// Carries the stream metadata needed to perform the logical decode pass.
64///
65/// Construct with [`LogicalValue::new`] after the physical decode pass fills a
66/// `&[u32]` or `&[u64]` buffer, then call the appropriate `decode_*` method,
67/// passing that slice as `data`.
68#[derive(Debug, PartialEq)]
69pub struct LogicalValue {
70    pub(crate) meta: StreamMeta,
71}
72
73// Physical encoding types
74
75/// Dictionary type used for a column, as stored in the tile
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, TryFromPrimitive)]
77#[repr(u8)]
78pub enum DictionaryType {
79    None = 0,
80    Single = 1,
81    Shared = 2,
82    Vertex = 3,
83    Morton = 4,
84    Fsst = 5,
85}
86
87/// Offset type used for a column, as stored in the tile
88#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, TryFromPrimitive)]
89#[repr(u8)]
90pub enum OffsetType {
91    Vertex = 0,
92    Index = 1,
93    String = 2,
94    Key = 3,
95}
96
97/// Length type used for a column, as stored in the tile
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, TryFromPrimitive)]
99#[repr(u8)]
100pub enum LengthType {
101    VarBinary = 0,
102    Geometries = 1,
103    Parts = 2,
104    Rings = 3,
105    Triangles = 4,
106    Symbol = 5,
107    Dictionary = 6,
108}
109
110/// How should the stream be interpreted at the physical level (first pass of decoding)
111#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
112pub enum StreamType {
113    Present,
114    Data(DictionaryType),
115    Offset(OffsetType),
116    Length(LengthType),
117}
118
119/// Physical encoding used for a column, as stored in the tile
120#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, TryFromPrimitive)]
121#[repr(u8)]
122pub enum PhysicalEncoding {
123    None = 0,
124    /// Preferred, tends to produce the best compression ratio and decoding performance.
125    /// But currently limited to 32-bit integer.
126    FastPFor256 = 1,
127    /// Can produce better results in combination with a heavyweight compression scheme like `Gzip`.
128    /// Simple compression scheme where the encoding is easier to implement compared to `FastPfor`.
129    VarInt = 2,
130}
131
132// RawStream types
133
134#[derive(Debug, Clone, Copy, PartialEq)]
135pub struct IntEncoding {
136    pub logical: LogicalEncoding,
137    pub physical: PhysicalEncoding,
138}
139
140impl IntEncoding {
141    #[must_use]
142    pub(crate) const fn new(logical: LogicalEncoding, physical: PhysicalEncoding) -> Self {
143        Self { logical, physical }
144    }
145
146    #[must_use]
147    pub(crate) const fn none() -> Self {
148        Self::new(LogicalEncoding::None, PhysicalEncoding::None)
149    }
150}
151
152/// Metadata about an encoded stream
153#[derive(Clone, Copy, Dbg, PartialEq)]
154pub struct StreamMeta {
155    #[dbg(formatter = "compact_dbg")]
156    pub stream_type: StreamType,
157    #[dbg(formatter = "compact_dbg")]
158    pub encoding: IntEncoding,
159    pub(crate) num_values: u32,
160}
161
162impl StreamMeta {
163    #[inline]
164    pub(crate) fn new(stream_type: StreamType, encoding: IntEncoding, num_values: u32) -> Self {
165        Self {
166            stream_type,
167            encoding,
168            num_values,
169        }
170    }
171
172    #[inline]
173    pub(crate) fn new2(
174        stream_type: StreamType,
175        logical: LogicalEncoding,
176        physical: PhysicalEncoding,
177        num_values: usize,
178    ) -> MltResult<Self> {
179        let enc = IntEncoding::new(logical, physical);
180        Ok(Self::new(stream_type, enc, u32::try_from(num_values)?))
181    }
182
183    #[inline]
184    pub(crate) fn new_none(stream_type: StreamType, num_values: usize) -> MltResult<Self> {
185        let enc = IntEncoding::none();
186        Ok(Self::new(stream_type, enc, u32::try_from(num_values)?))
187    }
188}
189
190/// Representation of an encoded stream
191#[derive(Clone, Dbg, PartialEq)]
192pub struct RawStream<'a> {
193    pub meta: StreamMeta,
194    #[dbg(formatter = "bytes_dbg")]
195    pub(crate) data: &'a [u8],
196}
197
198impl<'a> RawStream<'a> {
199    #[must_use]
200    pub(crate) fn new(meta: StreamMeta, data: &'a [u8]) -> Self {
201        Self { meta, data }
202    }
203}
mlt_core/decoder/stream/model.rs

mlt_core/decoder/stream/
model.rs
