Skip to main content

ocio_rs/transform/
range.rs

1use std::ffi::c_void;
2use std::ptr::NonNull;
3
4use crate::{BitDepth, OcioError, RangeStyle, Result, TransformDirection};
5use ocio_sys;
6
7/// Clamps and rescales numeric ranges between input and output domains.
8pub struct RangeTransform {
9    pub(crate) handle: NonNull<c_void>,
10}
11
12impl RangeTransform {
13    /// Create a new identity range transform.
14    pub fn create() -> Result<Self> {
15        crate::clear_last_error();
16        let handle = unsafe { ocio_sys::ocio_range_transform_create() };
17        crate::handle_result(handle).map(|handle| Self { handle })
18    }
19
20    /// Return the current range style.
21    pub fn style(&self) -> RangeStyle {
22        let s = unsafe { ocio_sys::ocio_range_transform_get_style(self.handle.as_ptr()) };
23        match s {
24            1 => RangeStyle::Clamp,
25            _ => RangeStyle::NoClamp,
26        }
27    }
28
29    /// Set the range style.
30    pub fn set_style(&self, style: RangeStyle) {
31        self.try_set_style(style)
32            .expect("failed to set range style");
33    }
34
35    /// Set the range style and surface any OCIO validation error.
36    pub fn try_set_style(&self, style: RangeStyle) -> Result<()> {
37        crate::clear_last_error();
38        unsafe { ocio_sys::ocio_range_transform_set_style(self.handle.as_ptr(), style as i32) };
39        crate::ocio_call_status()
40    }
41
42    /// Return the minimum input value.
43    pub fn min_in_value(&self) -> f64 {
44        unsafe { ocio_sys::ocio_range_transform_get_min_in_value(self.handle.as_ptr()) }
45    }
46
47    /// Set the minimum input value.
48    pub fn set_min_in_value(&self, value: f64) {
49        self.try_set_min_in_value(value)
50            .expect("failed to set range minimum input value");
51    }
52
53    /// Set the minimum input endpoint and surface any OCIO validation error.
54    pub fn try_set_min_in_value(&self, value: f64) -> Result<()> {
55        crate::clear_last_error();
56        unsafe { ocio_sys::ocio_range_transform_set_min_in_value(self.handle.as_ptr(), value) };
57        crate::ocio_call_status()
58    }
59
60    /// Return the maximum input value.
61    pub fn max_in_value(&self) -> f64 {
62        unsafe { ocio_sys::ocio_range_transform_get_max_in_value(self.handle.as_ptr()) }
63    }
64
65    /// Set the maximum input value.
66    pub fn set_max_in_value(&self, value: f64) {
67        self.try_set_max_in_value(value)
68            .expect("failed to set range maximum input value");
69    }
70
71    /// Set the maximum input endpoint and surface any OCIO validation error.
72    pub fn try_set_max_in_value(&self, value: f64) -> Result<()> {
73        crate::clear_last_error();
74        unsafe { ocio_sys::ocio_range_transform_set_max_in_value(self.handle.as_ptr(), value) };
75        crate::ocio_call_status()
76    }
77
78    /// Return the minimum output value.
79    pub fn min_out_value(&self) -> f64 {
80        unsafe { ocio_sys::ocio_range_transform_get_min_out_value(self.handle.as_ptr()) }
81    }
82
83    /// Set the minimum output value.
84    pub fn set_min_out_value(&self, value: f64) {
85        self.try_set_min_out_value(value)
86            .expect("failed to set range minimum output value");
87    }
88
89    /// Set the minimum output endpoint and surface any OCIO validation error.
90    pub fn try_set_min_out_value(&self, value: f64) -> Result<()> {
91        crate::clear_last_error();
92        unsafe { ocio_sys::ocio_range_transform_set_min_out_value(self.handle.as_ptr(), value) };
93        crate::ocio_call_status()
94    }
95
96    /// Return the maximum output value.
97    pub fn max_out_value(&self) -> f64 {
98        unsafe { ocio_sys::ocio_range_transform_get_max_out_value(self.handle.as_ptr()) }
99    }
100
101    /// Set the maximum output value.
102    pub fn set_max_out_value(&self, value: f64) {
103        self.try_set_max_out_value(value)
104            .expect("failed to set range maximum output value");
105    }
106
107    /// Set the maximum output endpoint and surface any OCIO validation error.
108    pub fn try_set_max_out_value(&self, value: f64) -> Result<()> {
109        crate::clear_last_error();
110        unsafe { ocio_sys::ocio_range_transform_set_max_out_value(self.handle.as_ptr(), value) };
111        crate::ocio_call_status()
112    }
113
114    /// Return the transform direction.
115    pub fn direction(&self) -> TransformDirection {
116        let dir = unsafe { ocio_sys::ocio_range_transform_get_direction(self.handle.as_ptr()) };
117        match dir {
118            1 => TransformDirection::Inverse,
119            _ => TransformDirection::Forward,
120        }
121    }
122
123    /// Set the transform direction.
124    pub fn set_direction(&self, direction: TransformDirection) {
125        self.try_set_direction(direction)
126            .expect("failed to set range transform direction");
127    }
128
129    /// Set the transform direction and surface any OCIO validation error.
130    pub fn try_set_direction(&self, direction: TransformDirection) -> crate::Result<()> {
131        crate::clear_last_error();
132        unsafe {
133            ocio_sys::ocio_range_transform_set_direction(self.handle.as_ptr(), direction as i32);
134        }
135        crate::ocio_call_status()
136    }
137
138    /// Create an independent copy of this transform.
139    pub fn create_editable_copy(&self) -> Result<Self> {
140        crate::clear_last_error();
141        let handle = unsafe { ocio_sys::ocio_transform_create_editable_copy(self.handle.as_ptr()) };
142        crate::handle_result(handle).map(|handle| Self { handle })
143    }
144
145    /// Return whether the minimum input value is set.
146    pub fn has_min_in_value(&self) -> bool {
147        unsafe { ocio_sys::ocio_range_transform_has_min_in_value(self.handle.as_ptr()) }
148    }
149
150    /// Unset the minimum input value.
151    pub fn unset_min_in_value(&self) {
152        self.try_unset_min_in_value()
153            .expect("failed to unset range minimum input value");
154    }
155
156    /// Unset the minimum input endpoint and surface any OCIO validation error.
157    pub fn try_unset_min_in_value(&self) -> Result<()> {
158        crate::clear_last_error();
159        unsafe { ocio_sys::ocio_range_transform_unset_min_in_value(self.handle.as_ptr()) };
160        crate::ocio_call_status()
161    }
162
163    /// Return whether the maximum input value is set.
164    pub fn has_max_in_value(&self) -> bool {
165        unsafe { ocio_sys::ocio_range_transform_has_max_in_value(self.handle.as_ptr()) }
166    }
167
168    /// Unset the maximum input value.
169    pub fn unset_max_in_value(&self) {
170        self.try_unset_max_in_value()
171            .expect("failed to unset range maximum input value");
172    }
173
174    /// Unset the maximum input endpoint and surface any OCIO validation error.
175    pub fn try_unset_max_in_value(&self) -> Result<()> {
176        crate::clear_last_error();
177        unsafe { ocio_sys::ocio_range_transform_unset_max_in_value(self.handle.as_ptr()) };
178        crate::ocio_call_status()
179    }
180
181    /// Return whether the minimum output value is set.
182    pub fn has_min_out_value(&self) -> bool {
183        unsafe { ocio_sys::ocio_range_transform_has_min_out_value(self.handle.as_ptr()) }
184    }
185
186    /// Unset the minimum output value.
187    pub fn unset_min_out_value(&self) {
188        self.try_unset_min_out_value()
189            .expect("failed to unset range minimum output value");
190    }
191
192    /// Unset the minimum output endpoint and surface any OCIO validation error.
193    pub fn try_unset_min_out_value(&self) -> Result<()> {
194        crate::clear_last_error();
195        unsafe { ocio_sys::ocio_range_transform_unset_min_out_value(self.handle.as_ptr()) };
196        crate::ocio_call_status()
197    }
198
199    /// Return whether the maximum output value is set.
200    pub fn has_max_out_value(&self) -> bool {
201        unsafe { ocio_sys::ocio_range_transform_has_max_out_value(self.handle.as_ptr()) }
202    }
203
204    /// Unset the maximum output value.
205    pub fn unset_max_out_value(&self) {
206        self.try_unset_max_out_value()
207            .expect("failed to unset range maximum output value");
208    }
209
210    /// Unset the maximum output endpoint and surface any OCIO validation error.
211    pub fn try_unset_max_out_value(&self) -> Result<()> {
212        crate::clear_last_error();
213        unsafe { ocio_sys::ocio_range_transform_unset_max_out_value(self.handle.as_ptr()) };
214        crate::ocio_call_status()
215    }
216
217    /// Return the bit depth declared for file-based input serialization.
218    pub fn file_input_bit_depth(&self) -> BitDepth {
219        let b = unsafe {
220            ocio_sys::ocio_range_transform_get_file_input_bit_depth(self.handle.as_ptr())
221        };
222        match b {
223            1 => BitDepth::Uint8,
224            2 => BitDepth::Uint10,
225            3 => BitDepth::Uint12,
226            4 => BitDepth::Uint14,
227            5 => BitDepth::Uint16,
228            6 => BitDepth::Uint32,
229            7 => BitDepth::F16,
230            8 => BitDepth::F32,
231            _ => BitDepth::Unknown,
232        }
233    }
234
235    /// Set the serialized input bit depth.
236    pub fn set_file_input_bit_depth(&self, bit_depth: BitDepth) {
237        self.try_set_file_input_bit_depth(bit_depth)
238            .expect("failed to set range file input bit depth");
239    }
240
241    /// Set the serialized input bit depth and surface any OCIO validation error.
242    pub fn try_set_file_input_bit_depth(&self, bit_depth: BitDepth) -> Result<()> {
243        crate::clear_last_error();
244        unsafe {
245            ocio_sys::ocio_range_transform_set_file_input_bit_depth(
246                self.handle.as_ptr(),
247                bit_depth as i32,
248            )
249        };
250        crate::ocio_call_status()
251    }
252
253    /// Return the bit depth declared for file-based output serialization.
254    pub fn file_output_bit_depth(&self) -> BitDepth {
255        let b = unsafe {
256            ocio_sys::ocio_range_transform_get_file_output_bit_depth(self.handle.as_ptr())
257        };
258        match b {
259            1 => BitDepth::Uint8,
260            2 => BitDepth::Uint10,
261            3 => BitDepth::Uint12,
262            4 => BitDepth::Uint14,
263            5 => BitDepth::Uint16,
264            6 => BitDepth::Uint32,
265            7 => BitDepth::F16,
266            8 => BitDepth::F32,
267            _ => BitDepth::Unknown,
268        }
269    }
270
271    /// Set the serialized output bit depth.
272    pub fn set_file_output_bit_depth(&self, bit_depth: BitDepth) {
273        self.try_set_file_output_bit_depth(bit_depth)
274            .expect("failed to set range file output bit depth");
275    }
276
277    /// Set the serialized output bit depth and surface any OCIO validation error.
278    pub fn try_set_file_output_bit_depth(&self, bit_depth: BitDepth) -> Result<()> {
279        crate::clear_last_error();
280        unsafe {
281            ocio_sys::ocio_range_transform_set_file_output_bit_depth(
282                self.handle.as_ptr(),
283                bit_depth as i32,
284            )
285        };
286        crate::ocio_call_status()
287    }
288
289    /// Return format metadata attached to the transform, when available.
290    pub fn format_metadata(&self) -> Option<crate::FormatMetadata> {
291        let handle = unsafe { ocio_sys::ocio_transform_get_format_metadata(self.handle.as_ptr()) };
292        NonNull::new(handle).map(|h| crate::FormatMetadata { handle: h })
293    }
294
295    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
296    pub fn format_metadata_v1(&self) -> Option<crate::FormatMetadata> {
297        self.format_metadata()
298    }
299
300    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
301    pub fn format_metadata_v2(&self) -> Option<crate::FormatMetadata> {
302        self.format_metadata()
303    }
304
305    /// Return whether this transform is equivalent to `other`.
306    pub fn equals(&self, other: &Self) -> bool {
307        unsafe {
308            ocio_sys::ocio_range_transform_equals(self.handle.as_ptr(), other.handle.as_ptr())
309        }
310    }
311}
312
313impl Drop for RangeTransform {
314    fn drop(&mut self) {
315        unsafe { ocio_sys::ocio_range_transform_destroy(self.handle.as_ptr()) };
316    }
317}
318
319#[cfg(test)]
320mod tests {
321    use super::*;
322
323    #[test]
324    fn create_range() {
325        let rt = RangeTransform::create();
326        assert!(rt.is_ok());
327    }
328
329    #[test]
330    fn range_values_no_crash() {
331        let rt = RangeTransform::create().unwrap();
332        let _ = rt.min_in_value();
333        let _ = rt.max_in_value();
334        let _ = rt.min_out_value();
335        let _ = rt.max_out_value();
336        rt.try_set_min_in_value(0.1).unwrap();
337        rt.try_set_max_in_value(0.9).unwrap();
338        rt.try_set_min_out_value(0.05).unwrap();
339        rt.try_set_max_out_value(0.95).unwrap();
340    }
341
342    #[test]
343    fn has_unset_no_crash() {
344        let rt = RangeTransform::create().unwrap();
345        let _ = rt.has_min_in_value();
346        let _ = rt.has_max_in_value();
347        let _ = rt.has_min_out_value();
348        let _ = rt.has_max_out_value();
349        rt.try_unset_min_in_value().unwrap();
350        rt.try_unset_max_in_value().unwrap();
351        rt.try_unset_min_out_value().unwrap();
352        rt.try_unset_max_out_value().unwrap();
353    }
354
355    #[test]
356    fn bit_depth_no_crash() {
357        let rt = RangeTransform::create().unwrap();
358        let _ = rt.file_input_bit_depth();
359        rt.try_set_file_input_bit_depth(BitDepth::F32).unwrap();
360        let _ = rt.file_output_bit_depth();
361        rt.try_set_file_output_bit_depth(BitDepth::F32).unwrap();
362    }
363
364    #[test]
365    fn create_editable_copy_no_crash() {
366        let rt = RangeTransform::create().unwrap();
367        let _ = rt.create_editable_copy();
368    }
369
370    #[test]
371    fn format_metadata_no_crash() {
372        let rt = RangeTransform::create().unwrap();
373        let _ = rt.format_metadata();
374    }
375
376    #[test]
377    fn equals_no_crash() {
378        let a = RangeTransform::create().unwrap();
379        let b = RangeTransform::create().unwrap();
380        let _ = a.equals(&b);
381    }
382}