Skip to main content

ocio_rs/transform/
fixed_function.rs

1use std::ffi::c_void;
2use std::ptr::NonNull;
3
4use crate::{FixedFunctionStyle, OcioError, Result, TransformDirection};
5use ocio_sys;
6
7/// Wraps one of OCIO's fixed-function transform styles.
8pub struct FixedFunctionTransform {
9    pub(crate) handle: NonNull<c_void>,
10}
11
12impl FixedFunctionTransform {
13    /// Create a fixed-function transform with the given style using default parameters.
14    pub fn create(style: FixedFunctionStyle) -> Result<Self> {
15        crate::clear_last_error();
16        let handle = unsafe {
17            ocio_sys::ocio_fixed_function_transform_create_with_params(
18                style as i32,
19                std::ptr::null(),
20                0,
21            )
22        };
23        crate::handle_result(handle).map(|handle| Self { handle })
24    }
25
26    /// Create a fixed-function transform with the given style and custom parameters.
27    pub fn create_with_params(style: FixedFunctionStyle, params: &[f64]) -> Result<Self> {
28        crate::clear_last_error();
29        let handle = unsafe {
30            ocio_sys::ocio_fixed_function_transform_create_with_params(
31                style as i32,
32                params.as_ptr(),
33                params.len(),
34            )
35        };
36        crate::handle_result(handle).map(|handle| Self { handle })
37    }
38
39    /// Return the current fixed-function style.
40    ///
41    /// For compatibility, unknown styles fall back to `AcesRedMod03`.
42    /// Use [`Self::try_style`] to detect a style unavailable at this feature level.
43    pub fn style(&self) -> FixedFunctionStyle {
44        self.try_style().unwrap_or(FixedFunctionStyle::AcesRedMod03)
45    }
46
47    /// Return the current style, reporting unknown styles and native errors.
48    ///
49    /// A config may contain a style supported by the native library but not by
50    /// the enabled Rust interface feature. Enable the corresponding feature
51    /// to represent that style as a [`FixedFunctionStyle`].
52    pub fn try_style(&self) -> Result<FixedFunctionStyle> {
53        crate::clear_last_error();
54        let s = unsafe {
55            ocio_sys::ocio_fixed_function_transform_get_style(self.handle.as_ptr() as *mut c_void)
56        };
57        crate::ocio_call_status()?;
58        let style = match s {
59            0 => FixedFunctionStyle::AcesRedMod03,
60            1 => FixedFunctionStyle::AcesRedMod10,
61            2 => FixedFunctionStyle::AcesGlow03,
62            3 => FixedFunctionStyle::AcesGlow10,
63            4 => FixedFunctionStyle::AcesDarkToDim10,
64            5 => FixedFunctionStyle::Rec2100Surround,
65            6 => FixedFunctionStyle::RgbToHsv,
66            7 => FixedFunctionStyle::XyzToxyY,
67            8 => FixedFunctionStyle::XyzTouvY,
68            9 => FixedFunctionStyle::XyzToLuv,
69            10 => FixedFunctionStyle::AcesGamutMap02,
70            11 => FixedFunctionStyle::AcesGamutMap07,
71            12 => FixedFunctionStyle::AcesGamutCompress13,
72            13 => FixedFunctionStyle::LinToPq,
73            14 => FixedFunctionStyle::LinToGammaLog,
74            15 => FixedFunctionStyle::LinToDoubleLog,
75            16 => FixedFunctionStyle::AcesOutputTransform20,
76            17 => FixedFunctionStyle::AcesRgbToJmh20,
77            18 => FixedFunctionStyle::AcesTonescaleCompress20,
78            19 => FixedFunctionStyle::AcesGamutCompress20,
79            #[cfg(feature = "v2_5")]
80            20 => FixedFunctionStyle::RgbToHsyLin,
81            #[cfg(feature = "v2_5")]
82            21 => FixedFunctionStyle::RgbToHsyLog,
83            #[cfg(feature = "v2_5")]
84            22 => FixedFunctionStyle::RgbToHsyVid,
85            #[cfg(feature = "v2_6")]
86            23 => FixedFunctionStyle::AcesRgbToHmj20,
87            _ => {
88                return Err(OcioError::ValidationFailed(format!(
89                    "fixed-function style {s} is unavailable at the enabled interface level"
90                )))
91            }
92        };
93        Ok(style)
94    }
95
96    /// Set the fixed-function style, panicking on validation error.
97    pub fn set_style(&self, style: FixedFunctionStyle) {
98        self.try_set_style(style)
99            .expect("failed to set fixed-function style");
100    }
101
102    /// Set the fixed-function style and surface any OCIO validation error.
103    pub fn try_set_style(&self, style: FixedFunctionStyle) -> Result<()> {
104        crate::clear_last_error();
105        unsafe {
106            ocio_sys::ocio_fixed_function_transform_set_style(self.handle.as_ptr(), style as i32);
107        }
108        crate::ocio_call_status()
109    }
110
111    /// Return the number of parameters required by the current style.
112    pub fn try_num_params(&self) -> Result<i32> {
113        i32::try_from(self.try_num_params_usize()?).map_err(|_| {
114            OcioError::ValidationFailed("fixed-function parameter count exceeds i32::MAX".into())
115        })
116    }
117
118    /// Return the full native parameter count without narrowing it to `i32`.
119    pub fn try_num_params_usize(&self) -> Result<usize> {
120        crate::clear_last_error();
121        let v =
122            unsafe { ocio_sys::ocio_fixed_function_transform_get_num_params(self.handle.as_ptr()) };
123        crate::ocio_call_status()?;
124        Ok(v)
125    }
126
127    /// Return the number of parameters required by the current style.
128    pub fn num_params(&self) -> i32 {
129        self.try_num_params().unwrap_or(0)
130    }
131
132    /// Return the style-specific parameter values.
133    pub fn try_params(&self) -> Result<Vec<f64>> {
134        let n = self.try_num_params_usize()?;
135        if n == 0 {
136            return Ok(Vec::new());
137        }
138        let mut params = super::reserve_native_items(n, "FixedFunctionTransform::try_params")?;
139        params.resize(n, 0.0f64);
140        self.read_params(&mut params)?;
141        Ok(params)
142    }
143
144    /// Copy parameters into an exactly sized buffer without allocating.
145    /// A length mismatch leaves the buffer unchanged.
146    pub fn try_params_into(&self, output: &mut [f64]) -> Result<()> {
147        let count = self.try_num_params_usize()?;
148        if output.len() != count {
149            return Err(OcioError::InvalidInput(
150                "fixed-function parameter buffer length mismatch".into(),
151            ));
152        }
153        if count == 0 {
154            return Ok(());
155        }
156        self.read_params(output)
157    }
158
159    fn read_params(&self, output: &mut [f64]) -> Result<()> {
160        crate::clear_last_error();
161        unsafe {
162            ocio_sys::ocio_fixed_function_transform_get_params(
163                self.handle.as_ptr(),
164                output.as_mut_ptr() as *mut c_void,
165            );
166        }
167        crate::ocio_call_status()
168    }
169
170    /// Return the style-specific parameter values.
171    pub fn params(&self) -> Vec<f64> {
172        self.try_params().unwrap_or_default()
173    }
174
175    /// Set the style-specific parameters for this transform.
176    ///
177    /// OCIO may defer style-specific validation until the transform is
178    /// validated or used to construct a processor.
179    pub fn set_params(&self, params: &[f64]) -> Result<()> {
180        crate::clear_last_error();
181        unsafe {
182            ocio_sys::ocio_fixed_function_transform_set_params(
183                self.handle.as_ptr(),
184                params.as_ptr(),
185                params.len() as usize,
186            );
187        }
188        crate::ocio_call_status()
189    }
190
191    /// Return the evaluation direction.
192    pub fn direction(&self) -> TransformDirection {
193        let dir = unsafe {
194            ocio_sys::ocio_fixed_function_transform_get_direction(
195                self.handle.as_ptr() as *mut c_void
196            )
197        };
198        match dir {
199            1 => TransformDirection::Inverse,
200            _ => TransformDirection::Forward,
201        }
202    }
203
204    /// Set the evaluation direction, panicking on validation error.
205    pub fn set_direction(&self, direction: TransformDirection) {
206        self.try_set_direction(direction)
207            .expect("failed to set fixed function transform direction");
208    }
209
210    /// Set the transform direction and surface any OCIO validation error.
211    pub fn try_set_direction(&self, direction: TransformDirection) -> crate::Result<()> {
212        crate::clear_last_error();
213        unsafe {
214            ocio_sys::ocio_fixed_function_transform_set_direction(
215                self.handle.as_ptr(),
216                direction as i32,
217            );
218        }
219        crate::ocio_call_status()
220    }
221
222    /// Create an editable copy that is independent from the original transform.
223    pub fn create_editable_copy(&self) -> Result<Self> {
224        crate::clear_last_error();
225        let handle = unsafe {
226            ocio_sys::ocio_transform_create_editable_copy(self.handle.as_ptr() as *mut c_void)
227        };
228        crate::handle_result(handle).map(|handle| Self { handle })
229    }
230
231    /// Return format metadata attached to the transform, when available.
232    pub fn format_metadata(&self) -> Option<crate::FormatMetadata> {
233        let handle = unsafe { ocio_sys::ocio_transform_get_format_metadata(self.handle.as_ptr()) };
234        NonNull::new(handle).map(|h| crate::FormatMetadata { handle: h })
235    }
236
237    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
238    pub fn format_metadata_v1(&self) -> Option<crate::FormatMetadata> {
239        self.format_metadata()
240    }
241
242    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
243    pub fn format_metadata_v2(&self) -> Option<crate::FormatMetadata> {
244        self.format_metadata()
245    }
246
247    /// Return whether `other` is equivalent to this transform.
248    pub fn equals(&self, other: &Self) -> bool {
249        unsafe {
250            ocio_sys::ocio_fixed_function_transform_equals(
251                self.handle.as_ptr(),
252                other.handle.as_ptr(),
253            )
254        }
255    }
256}
257
258impl Drop for FixedFunctionTransform {
259    fn drop(&mut self) {
260        unsafe {
261            ocio_sys::ocio_fixed_function_transform_destroy(self.handle.as_ptr() as *mut c_void)
262        };
263    }
264}
265
266#[cfg(test)]
267mod tests {
268    use super::*;
269
270    #[test]
271    fn create_fixed_function() {
272        let ft = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03);
273        assert!(ft.is_ok());
274    }
275
276    #[test]
277    fn style_no_crash() {
278        let ft = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03).unwrap();
279        assert_eq!(ft.try_style().unwrap(), FixedFunctionStyle::AcesRedMod03);
280        ft.try_set_style(FixedFunctionStyle::RgbToHsv).unwrap();
281    }
282
283    #[test]
284    #[cfg(not(feature = "v2_5"))]
285    #[cfg_attr(ocio_stub, ignore = "requires native OpenColorIO 2.5 or later")]
286    fn newer_native_style_is_not_misreported_by_fallible_query() {
287        if crate::version_hex() < 0x0205_0000 {
288            return;
289        }
290        crate::clear_last_error();
291        let handle = unsafe {
292            ocio_sys::ocio_fixed_function_transform_create_with_params(20, std::ptr::null(), 0)
293        };
294        let ft = FixedFunctionTransform {
295            handle: crate::handle_result(handle).unwrap(),
296        };
297        assert!(matches!(
298            ft.try_style(),
299            Err(OcioError::ValidationFailed(_))
300        ));
301        assert_eq!(ft.style(), FixedFunctionStyle::AcesRedMod03);
302    }
303
304    #[test]
305    #[cfg(not(feature = "v2_6"))]
306    #[cfg_attr(ocio_stub, ignore = "requires native OpenColorIO 2.6 or later")]
307    fn native_26_hmj_is_not_misreported_at_older_interface_levels() {
308        if crate::version_hex() < 0x0206_0000 {
309            return;
310        }
311        let params = [0.7347, 0.2653, 0.0, 1.0, 0.0001, -0.0770, 0.32168, 0.33767];
312        crate::clear_last_error();
313        let handle = unsafe {
314            ocio_sys::ocio_fixed_function_transform_create_with_params(
315                23,
316                params.as_ptr(),
317                params.len(),
318            )
319        };
320        let ft = FixedFunctionTransform {
321            handle: crate::handle_result(handle).unwrap(),
322        };
323        assert!(matches!(
324            ft.try_style(),
325            Err(OcioError::ValidationFailed(_))
326        ));
327        assert_eq!(ft.style(), FixedFunctionStyle::AcesRedMod03);
328    }
329
330    #[test]
331    fn params_no_crash() {
332        let ft =
333            FixedFunctionTransform::create_with_params(FixedFunctionStyle::Rec2100Surround, &[1.0])
334                .unwrap();
335        let _ = ft.num_params();
336        let _ = ft.params();
337        ft.set_params(&[1.0]).unwrap();
338    }
339
340    #[test]
341    fn direction_no_crash() {
342        let ft = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03).unwrap();
343        let _ = ft.direction();
344        ft.set_direction(TransformDirection::Inverse);
345    }
346
347    #[test]
348    fn create_with_params() {
349        let ft =
350            FixedFunctionTransform::create_with_params(FixedFunctionStyle::Rec2100Surround, &[1.0]);
351        assert!(ft.is_ok());
352    }
353
354    #[test]
355    fn create_editable_copy_no_crash() {
356        let ft = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03).unwrap();
357        let _ = ft.create_editable_copy();
358    }
359
360    #[test]
361    fn format_metadata_no_crash() {
362        let ft = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03).unwrap();
363        let _ = ft.format_metadata();
364    }
365
366    #[test]
367    fn equals_no_crash() {
368        let a = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03).unwrap();
369        let b = FixedFunctionTransform::create(FixedFunctionStyle::AcesRedMod03).unwrap();
370        let _ = a.equals(&b);
371    }
372}