Skip to main content

meshoptimizer_rs/
quantize.rs

1//! Bit conversions from upstream quantization.cpp and meshoptimizer.h.
2use crate::Error;
3
4/// Quantize to an unsigned normalized integer with 0 through 30 bits.
5/// Infinities clamp; NaN follows upstream comparisons and becomes zero.
6///
7/// # Errors
8/// `InvalidParameter` if `bits` is outside the documented range.
9#[inline(always)]
10pub fn quantize_unorm(value: f32, bits: u32) -> Result<i32, Error> {
11    if bits > 30 {
12        return Err(Error::InvalidParameter);
13    }
14    let power = 1u32 << bits;
15    if value >= 1.0 {
16        // f32 rounds the endpoint upward starting at 24 bits, including
17        // the addition of 0.5 at exactly 24 bits.
18        return Ok(if bits >= 24 { power } else { power - 1 } as i32);
19    }
20    if value > 0.0 {
21        let scale = (power - 1) as f32;
22        Ok((value * scale + 0.5) as i32)
23    } else {
24        // Includes both zeros, negative infinity and all NaNs.
25        Ok(0)
26    }
27}
28
29/// Quantize to a signed normalized integer with 1 through 31 bits.
30/// Infinities clamp; NaN follows upstream comparisons and becomes the minimum.
31///
32/// # Errors
33/// `InvalidParameter` if `bits` is outside the documented range.
34#[inline]
35pub fn quantize_snorm(mut value: f32, bits: u32) -> Result<i32, Error> {
36    if !(1..=31).contains(&bits) {
37        return Err(Error::InvalidParameter);
38    }
39    let scale = ((1u32 << (bits - 1)) - 1) as f32;
40    let round = if value >= 0.0 { 0.5 } else { -0.5 };
41    value = if value >= -1.0 { value } else { -1.0 };
42    value = if value <= 1.0 { value } else { 1.0 };
43    Ok((value * scale + round) as i32)
44}
45
46/// Convert to upstream's half representation, flushing subnormals and
47/// canonicalizing NaNs to signed quiet NaNs.
48#[inline]
49pub fn quantize_half(value: f32) -> u16 {
50    let ui = value.to_bits();
51    let sign = (ui >> 16) & 0x8000;
52    let em = ui & 0x7fffffff;
53    // Clamp before rebiasing so large finite values and infinities share
54    // the same arithmetic path; NaNs add the quiet bit below.
55    let capped = em.min(143 << 23);
56    let half = capped.wrapping_sub(112 << 23).wrapping_add(1 << 12) >> 13;
57    let normal = 0u32.wrapping_sub(u32::from(em >= 113 << 23));
58    let half = (half & normal) | (u32::from(em > 255 << 23) << 9);
59    (sign | half) as u16
60}
61
62/// Round to 0 through 23 mantissa bits. Preserve infinity and NaN payloads;
63/// flush all exponent-zero values, including negative zero, to positive zero.
64///
65/// # Errors
66/// `InvalidParameter` if `bits` is outside the documented range.
67#[inline]
68pub fn quantize_float(value: f32, bits: u32) -> Result<f32, Error> {
69    if bits > 23 {
70        return Err(Error::InvalidParameter);
71    }
72    let mut ui = value.to_bits();
73    let mask = (1u32 << (23 - bits)) - 1;
74    let round = (1u32 << (23 - bits)) >> 1;
75    let exponent = ui & 0x7f800000;
76    if exponent != 0x7f800000 {
77        ui = ui.wrapping_add(round) & !mask;
78    }
79    if exponent == 0 {
80        ui = 0;
81    }
82    Ok(f32::from_bits(ui))
83}
84
85/// Expand a half value; flush half subnormals, preserve signed zero and NaN payloads.
86#[inline]
87pub fn dequantize_half(half: u16) -> f32 {
88    let sign = u32::from(half & 0x8000) << 16;
89    let em = u32::from(half & 0x7fff);
90    let mut result = (em + (112 << 10)) << 13;
91    if em < 1 << 10 {
92        result = 0;
93    }
94    if em >= 31 << 10 {
95        result += 112 << 23;
96    }
97    f32::from_bits(sign | result)
98}
99
100/// Compute the exponent of a conservative signed position grid.
101/// Bounds must be finite and ordered; `min_exp` is at least -126 and
102/// `max_bits` is 2 through 24. Overflowing scaled bounds return an error.
103///
104/// # Errors
105/// `InvalidParameter` for invalid bounds or exponent/bit settings;
106/// `NumericalFailure` for overflowing scaled bounds; `SizeOverflow` if the exponent cannot be advanced.
107#[inline]
108pub fn compute_position_exponent(
109    min: [f32; 3],
110    max: [f32; 3],
111    min_exp: i32,
112    max_bits: u32,
113) -> Result<i32, Error> {
114    if min_exp < -126 || !(2..=24).contains(&max_bits) {
115        return Err(Error::InvalidParameter);
116    }
117    let mut maxc = 0.0f32;
118    for k in 0..3 {
119        if !min[k].is_finite() || !max[k].is_finite() || min[k] > max[k] {
120            return Err(Error::InvalidParameter);
121        }
122        maxc = if maxc < min[k].abs() {
123            min[k].abs()
124        } else {
125            maxc
126        };
127        maxc = if maxc < max[k].abs() {
128            max[k].abs()
129        } else {
130            maxc
131        };
132    }
133    let (fraction, exponent) = libm::frexpf(maxc);
134    let offset = 23 - i32::from(fraction >= 1.0 - f32::EPSILON / 2.0);
135    let mut exp = min_exp.max(exponent - offset);
136    let scale = libm::ldexpf(1.0, -exp);
137    let mut range = 0.0f32;
138    for k in 0..3 {
139        let a = libm::floorf(min[k] * scale);
140        let v = libm::ceilf(max[k] * scale);
141        let d = v - a;
142        if !d.is_finite() {
143            return Err(Error::NumericalFailure);
144        }
145        range = if range < d { d } else { range };
146    }
147    let (fraction, exponent) = libm::frexpf(range);
148    if exponent > max_bits as i32 {
149        exp = exp
150            .checked_add(exponent - max_bits as i32)
151            .ok_or(Error::SizeOverflow)?;
152        exp = exp
153            .checked_add(i32::from(
154                fraction >= 1.0 - 1.0 / ((1u32 << max_bits) - 1) as f32,
155            ))
156            .ok_or(Error::SizeOverflow)?;
157    }
158    Ok(exp)
159}