1
2// calculations inspired by
3// https://github.com/AcademySoftwareFoundation/openexr/blob/master/OpenEXR/IlmImf/ImfTiledMisc.cpp
4
5//! Simple math utilities.
6
7use std::convert::TryFrom;
8use crate::error::{i32_to_usize};
9use crate::error::Result;
10use std::ops::{Add, Sub, Div, Mul};
11use std::fmt::Debug;
12
13/// Simple two-dimensional vector of any numerical type.
14/// Supports only few mathematical operations
15/// as this is used mainly as data struct.
16#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
17pub struct Vec2<T> (pub T, pub T);
18
19impl<T> Vec2<T> {
20
21 /// Returns the vector with the maximum of either coordinates.
22 pub fn max(self, other: Self) -> Self where T: Ord {
23 Vec2(self.0.max(other.0), self.1.max(other.1))
24 }
25
26 /// Returns the vector with the minimum of either coordinates.
27 pub fn min(self, other: Self) -> Self where T: Ord {
28 Vec2(self.0.min(other.0), self.1.min(other.1))
29 }
30
31 /// Try to convert all components of this vector to a new type,
32 /// yielding either a vector of that new type, or an error.
33 pub fn try_from<S>(value: Vec2<S>) -> std::result::Result<Self, T::Error> where T: TryFrom<S> {
34 let x = T::try_from(value.0)?;
35 let y = T::try_from(value.1)?;
36 Ok(Vec2(x, y))
37 }
38
39
40
41 /// Seeing this vector as a dimension or size (width and height),
42 /// this returns the area that this dimensions contains (`width * height`).
43 #[inline] pub fn area(self) -> T where T: std::ops::Mul<T, Output = T> {
44 self.0 * self.1
45 }
46
47 /// The first component of this 2D vector.
48 #[inline] pub fn x(self) -> T { self.0 }
49
50 /// The second component of this 2D vector.
51 #[inline] pub fn y(self) -> T { self.1 }
52
53 /// The first component of this 2D vector.
54 #[inline] pub fn width(self) -> T { self.0 }
55
56 /// The second component of this 2D vector.
57 #[inline] pub fn height(self) -> T { self.1 }
58
59 // TODO use this!
60 /// Convert this two-dimensional coordinate to an index suited for one-dimensional flattened image arrays.
61 /// Works for images that store the pixels row by row, one after another, in a single array.
62 /// In debug mode, panics for an index out of bounds.
63 #[inline] pub fn flat_index_for_size(self, resolution: Vec2<T>) -> T
64 where T: Copy + Debug + Ord + Mul<Output=T> + Add<Output=T>
65 {
66 debug_assert!(
67 self.x() < resolution.width() && self.y() < resolution.height(),
68 "Vec2 index {:?} is invalid for resolution {:?}", self, resolution
69 );
70
71 let Vec2(x, y) = self;
72 y * resolution.width() + x
73 }
74}
75
76
77
78impl Vec2<i32> {
79
80 /// Try to convert to [`Vec2<usize>`], returning an error on negative numbers.
81 pub fn to_usize(self, error_message: &'static str) -> Result<Vec2<usize>> {
82 let x: usize = i32_to_usize(self.0, error_message)?;
83 let y: usize = i32_to_usize(self.1, error_message)?;
84 Ok(Vec2(x, y))
85 }
86
87}
88
89impl Vec2<usize> {
90
91 /// Panics for too large values
92 pub fn to_i32(self) -> Vec2<i32> {
93 let x: i32 = i32::try_from(self.0).expect(msg:"vector x coordinate too large");
94 let y: i32 = i32::try_from(self.1).expect(msg:"vector y coordinate too large");
95 Vec2(x, y)
96 }
97
98}
99
100
101impl<T: std::ops::Add<T>> std::ops::Add<Vec2<T>> for Vec2<T> {
102 type Output = Vec2<T::Output>;
103 fn add(self, other: Vec2<T>) -> Self::Output {
104 Vec2(self.0 + other.0, self.1 + other.1)
105 }
106}
107
108impl<T: std::ops::Sub<T>> std::ops::Sub<Vec2<T>> for Vec2<T> {
109 type Output = Vec2<T::Output>;
110 fn sub(self, other: Vec2<T>) -> Self::Output {
111 Vec2(self.0 - other.0, self.1 - other.1)
112 }
113}
114
115impl<T: std::ops::Div<T>> std::ops::Div<Vec2<T>> for Vec2<T> {
116 type Output = Vec2<T::Output>;
117 fn div(self, other: Vec2<T>) -> Self::Output {
118 Vec2(self.0 / other.0, self.1 / other.1)
119 }
120}
121
122impl<T: std::ops::Mul<T>> std::ops::Mul<Vec2<T>> for Vec2<T> {
123 type Output = Vec2<T::Output>;
124 fn mul(self, other: Vec2<T>) -> Self::Output {
125 Vec2(self.0 * other.0, self.1 * other.1)
126 }
127}
128
129impl<T> std::ops::Neg for Vec2<T> where T: std::ops::Neg<Output=T> {
130 type Output = Vec2<T>;
131 fn neg(self) -> Self::Output { Vec2(-self.0, -self.1) }
132}
133
134impl<T> From<(T, T)> for Vec2<T> {
135 fn from((x: T, y: T): (T, T)) -> Self { Vec2(x, y) }
136}
137
138impl<T> From<Vec2<T>> for (T, T) {
139 fn from(vec2: Vec2<T>) -> Self { (vec2.0, vec2.1) }
140}
141
142/// Computes `floor(log(x)/log(2))`. Returns 0 where argument is 0.
143// TODO does rust std not provide this?
144pub(crate) fn floor_log_2(mut number: u32) -> u32 {
145 let mut log: u32 = 0;
146
147 // TODO check if this unrolls properly?
148 while number > 1 {
149 log += 1;
150 number >>= 1;
151 }
152
153 log
154}
155
156
157/// Computes `ceil(log(x)/log(2))`. Returns 0 where argument is 0.
158// taken from https://github.com/openexr/openexr/blob/master/OpenEXR/IlmImf/ImfTiledMisc.cpp
159// TODO does rust std not provide this?
160pub(crate) fn ceil_log_2(mut number: u32) -> u32 {
161 let mut log: u32 = 0;
162 let mut round_up: u32 = 0;
163
164 // TODO check if this unrolls properly
165 while number > 1 {
166 if number & 1 != 0 {
167 round_up = 1;
168 }
169
170 log += 1;
171 number >>= 1;
172 }
173
174 log + round_up
175}
176
177
178/// Round up or down in specific calculations.
179#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
180pub enum RoundingMode {
181
182 /// Round down.
183 Down,
184
185 /// Round up.
186 Up,
187}
188
189impl RoundingMode {
190 pub(crate) fn log2(self, number: u32) -> u32 {
191 match self {
192 RoundingMode::Down => self::floor_log_2(number),
193 RoundingMode::Up => self::ceil_log_2(number),
194 }
195 }
196
197 /// Only works for positive numbers.
198 pub(crate) fn divide<T>(self, dividend: T, divisor: T) -> T
199 where T: Copy + Add<Output = T> + Sub<Output = T> + Div<Output = T> + From<u8> + std::cmp::PartialOrd
200 {
201 assert!(
202 dividend >= T::from(0) && divisor >= T::from(1),
203 "division with rounding up only works for positive numbers"
204 );
205
206 match self {
207 RoundingMode::Up => (dividend + divisor - T::from(1_u8)) / divisor, // only works for positive numbers
208 RoundingMode::Down => dividend / divisor,
209 }
210 }
211}
212
213// TODO log2 tests
214