Skip to main content

ocio_rs/transform/
grading_primary.rs

1use std::ffi::c_void;
2use std::ptr::NonNull;
3
4use crate::{grading::GradingPrimary, GradingStyle, OcioError, Result, TransformDirection};
5use ocio_sys;
6
7/// OCIO primary grading transform for lift/gamma/gain-style controls.
8pub struct GradingPrimaryTransform {
9    pub(crate) handle: NonNull<c_void>,
10}
11
12impl GradingPrimaryTransform {
13    /// Create a primary grading transform with the given style (alias for [`Self::create`]).
14    pub fn create_with_style(style: GradingStyle) -> Result<Self> {
15        Self::create(style)
16    }
17
18    /// Create a new primary grading transform with the given style.
19    pub fn create(style: GradingStyle) -> Result<Self> {
20        crate::clear_last_error();
21        let handle =
22            unsafe { ocio_sys::ocio_grading_primary_transform_create_with_style(style as i32) };
23        crate::handle_result(handle).map(|handle| Self { handle })
24    }
25
26    /// Create an independent, editable copy of this transform.
27    pub fn create_editable_copy(&self) -> Result<Self> {
28        crate::clear_last_error();
29        let handle = unsafe { ocio_sys::ocio_transform_create_editable_copy(self.handle.as_ptr()) };
30        crate::handle_result(handle).map(|handle| Self { handle })
31    }
32
33    /// Return the current grading style (Log, Lin, or Video).
34    pub fn style(&self) -> GradingStyle {
35        let v = unsafe { ocio_sys::ocio_grading_primary_transform_get_style(self.handle.as_ptr()) };
36        match v {
37            1 => GradingStyle::Lin,
38            2 => GradingStyle::Video,
39            _ => GradingStyle::Log,
40        }
41    }
42
43    /// Set the grading style, panicking on failure.
44    pub fn set_style(&self, style: GradingStyle) {
45        self.try_set_style(style)
46            .expect("failed to set primary grading style");
47    }
48
49    /// Set the grading style and surface any OCIO validation error.
50    pub fn try_set_style(&self, style: GradingStyle) -> Result<()> {
51        crate::clear_last_error();
52        unsafe {
53            ocio_sys::ocio_grading_primary_transform_set_style(self.handle.as_ptr(), style as i32);
54        }
55        crate::ocio_call_status()
56    }
57
58    /// Return the current primary grading values, or style defaults on failure.
59    /// Use [`Self::try_value`] to distinguish an OCIO error from real values.
60    pub fn value(&self) -> GradingPrimary {
61        self.try_value()
62            .unwrap_or_else(|_| GradingPrimary::new(self.style()))
63    }
64
65    /// Return the current primary grading values, preserving native errors.
66    /// The fixed-size value is copied into a stack buffer without allocation.
67    pub fn try_value(&self) -> Result<GradingPrimary> {
68        let mut flat = [0.0f64; 34];
69        crate::clear_last_error();
70        let copied = unsafe {
71            ocio_sys::ocio_grading_primary_transform_copy_value(
72                self.handle.as_ptr(),
73                flat.as_mut_ptr(),
74                flat.len(),
75            )
76        };
77        crate::ocio_call_status()?;
78        if !copied {
79            return Err(OcioError::Ocio(
80                "failed to read primary grading value".into(),
81            ));
82        }
83        Ok(GradingPrimary::from_flat_array(&flat))
84    }
85
86    #[deprecated(since = "0.2.0", note = "compat alias; prefer value()")]
87    pub fn copy_value(&self) -> GradingPrimary {
88        self.value()
89    }
90
91    /// Set the primary grading control values, panicking on failure.
92    pub fn set_value(&self, value: &GradingPrimary) {
93        self.try_set_value(value)
94            .expect("failed to set primary grading value");
95    }
96
97    /// Replace the primary grading controls and surface any OCIO validation error.
98    pub fn try_set_value(&self, value: &GradingPrimary) -> Result<()> {
99        let flat = value.to_flat_array();
100        crate::clear_last_error();
101        let accepted = unsafe {
102            ocio_sys::ocio_grading_primary_transform_set_value_from_f64(
103                self.handle.as_ptr(),
104                flat.as_ptr(),
105                flat.len(),
106            )
107        };
108        if accepted {
109            crate::ocio_call_status()
110        } else {
111            crate::ocio_call_status()?;
112            Err(OcioError::Ocio(
113                "GradingPrimaryTransform::set_value was rejected".to_owned(),
114            ))
115        }
116    }
117
118    #[deprecated(
119        since = "0.2.0",
120        note = "compat alias; prefer set_value(&GradingPrimary)"
121    )]
122    pub fn set_value_from_f64(&self, value: &GradingPrimary) {
123        self.set_value(value);
124    }
125
126    /// Return `true` if this transform is dynamic (values can be updated at runtime).
127    pub fn is_dynamic(&self) -> bool {
128        unsafe { ocio_sys::ocio_grading_primary_transform_is_dynamic(self.handle.as_ptr()) }
129    }
130
131    /// Make this transform dynamic, panicking on failure.
132    pub fn make_dynamic(&self) {
133        self.try_make_dynamic()
134            .expect("failed to make primary grading dynamic");
135    }
136
137    /// Make this transform dynamic and surface any OCIO validation error.
138    pub fn try_make_dynamic(&self) -> Result<()> {
139        crate::clear_last_error();
140        unsafe {
141            ocio_sys::ocio_grading_primary_transform_make_dynamic(self.handle.as_ptr());
142        }
143        crate::ocio_call_status()
144    }
145
146    /// Make this transform non-dynamic, panicking on failure.
147    pub fn make_non_dynamic(&self) {
148        self.try_make_non_dynamic()
149            .expect("failed to make primary grading non-dynamic");
150    }
151
152    /// Make this transform non-dynamic and surface any OCIO validation error.
153    pub fn try_make_non_dynamic(&self) -> Result<()> {
154        crate::clear_last_error();
155        unsafe {
156            ocio_sys::ocio_grading_primary_transform_make_non_dynamic(self.handle.as_ptr());
157        }
158        crate::ocio_call_status()
159    }
160
161    /// Return the current transform direction.
162    pub fn direction(&self) -> TransformDirection {
163        let dir =
164            unsafe { ocio_sys::ocio_grading_primary_transform_get_direction(self.handle.as_ptr()) };
165        match dir {
166            1 => TransformDirection::Inverse,
167            _ => TransformDirection::Forward,
168        }
169    }
170
171    /// Set the transform direction, panicking on failure.
172    pub fn set_direction(&self, direction: TransformDirection) {
173        self.try_set_direction(direction)
174            .expect("failed to set primary grading direction");
175    }
176
177    /// Set the transform direction and surface any OCIO validation error.
178    pub fn try_set_direction(&self, direction: TransformDirection) -> Result<()> {
179        crate::clear_last_error();
180        unsafe {
181            ocio_sys::ocio_grading_primary_transform_set_direction(
182                self.handle.as_ptr(),
183                direction as i32,
184            );
185        }
186        crate::ocio_call_status()
187    }
188
189    /// Return the format metadata associated with this transform, if any.
190    pub fn format_metadata(&self) -> Option<crate::FormatMetadata> {
191        let handle = unsafe { ocio_sys::ocio_transform_get_format_metadata(self.handle.as_ptr()) };
192        NonNull::new(handle).map(|h| crate::FormatMetadata { handle: h })
193    }
194
195    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
196    pub fn format_metadata_v1(&self) -> Option<crate::FormatMetadata> {
197        self.format_metadata()
198    }
199
200    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
201    pub fn format_metadata_v2(&self) -> Option<crate::FormatMetadata> {
202        self.format_metadata()
203    }
204
205    /// Return `true` if this transform is equal to `other`.
206    pub fn equals(&self, other: &Self) -> bool {
207        unsafe {
208            ocio_sys::ocio_grading_primary_transform_equals(
209                self.handle.as_ptr(),
210                other.handle.as_ptr(),
211            )
212        }
213    }
214}
215
216impl Drop for GradingPrimaryTransform {
217    fn drop(&mut self) {
218        unsafe { ocio_sys::ocio_grading_primary_transform_destroy(self.handle.as_ptr()) };
219    }
220}
221
222#[cfg(test)]
223mod tests {
224    use super::*;
225
226    #[test]
227    #[cfg(ocio_stub)]
228    fn fallible_value_reports_missing_native_backend() {
229        let transform = GradingPrimaryTransform::create(GradingStyle::Lin).unwrap();
230        assert!(transform.try_value().is_err());
231        assert_eq!(transform.value(), GradingPrimary::new(transform.style()));
232    }
233
234    #[test]
235    fn create_grading_primary() {
236        let t = GradingPrimaryTransform::create(GradingStyle::Log);
237        assert!(t.is_ok());
238    }
239
240    #[test]
241    fn grading_primary_methods_no_crash() {
242        let t = GradingPrimaryTransform::create(GradingStyle::Lin).unwrap();
243        let _ = t.style();
244        let _ = t.value();
245        let _ = t.is_dynamic();
246        let _ = t.direction();
247    }
248
249    #[test]
250    fn set_style_no_crash() {
251        let t = GradingPrimaryTransform::create(GradingStyle::Log).unwrap();
252        t.try_set_style(GradingStyle::Lin).unwrap();
253        t.try_set_style(GradingStyle::Video).unwrap();
254    }
255
256    #[test]
257    fn set_value_no_crash() {
258        let t = GradingPrimaryTransform::create(GradingStyle::Log).unwrap();
259        let v = GradingPrimary::new(GradingStyle::Log);
260        t.try_set_value(&v).unwrap();
261    }
262
263    #[test]
264    fn make_dynamic_no_crash() {
265        let t = GradingPrimaryTransform::create(GradingStyle::Log).unwrap();
266        t.try_make_dynamic().unwrap();
267        t.try_make_non_dynamic().unwrap();
268    }
269
270    #[test]
271    fn direction_no_crash() {
272        let t = GradingPrimaryTransform::create(GradingStyle::Log).unwrap();
273        t.set_direction(TransformDirection::Inverse);
274    }
275
276    #[test]
277    fn create_editable_copy_no_crash() {
278        let t = GradingPrimaryTransform::create(GradingStyle::Log).unwrap();
279        let _ = t.create_editable_copy();
280    }
281
282    #[test]
283    fn format_metadata_no_crash() {
284        let t = GradingPrimaryTransform::create(GradingStyle::Log).unwrap();
285        let _ = t.format_metadata();
286    }
287}