Skip to main content

ocio_rs/transform/
exposure_contrast.rs

1use std::ffi::c_void;
2use std::ptr::NonNull;
3
4use crate::{ExposureContrastStyle, OcioError, Result, TransformDirection};
5use ocio_sys;
6
7/// Exposure/contrast/gamma style transform with optional dynamic controls.
8///
9/// The `try_*` queries preserve native errors. The infallible getters retain
10/// their compatibility fallback values if a native query fails.
11pub struct ExposureContrastTransform {
12    pub(crate) handle: NonNull<c_void>,
13}
14
15macro_rules! fallible_query {
16    ($name:ident, $ffi:ident, $result:ty, $doc:literal) => {
17        #[doc = $doc]
18        pub fn $name(&self) -> Result<$result> {
19            self.try_query(ocio_sys::$ffi)
20        }
21    };
22}
23
24impl ExposureContrastTransform {
25    fn try_query<T>(&self, getter: unsafe extern "C" fn(*mut c_void) -> T) -> Result<T> {
26        if cfg!(ocio_stub) {
27            return Err(OcioError::Ocio(
28                "exposure/contrast query requires native OpenColorIO".into(),
29            ));
30        }
31        crate::clear_last_error();
32        let value = unsafe { getter(self.handle.as_ptr()) };
33        crate::ocio_call_status()?;
34        Ok(value)
35    }
36
37    fallible_query!(
38        try_exposure,
39        ocio_exposure_contrast_transform_get_exposure,
40        f64,
41        "Read exposure while preserving native errors."
42    );
43    fallible_query!(
44        try_contrast,
45        ocio_exposure_contrast_transform_get_contrast,
46        f64,
47        "Read contrast while preserving native errors."
48    );
49    fallible_query!(
50        try_gamma,
51        ocio_exposure_contrast_transform_get_gamma,
52        f64,
53        "Read gamma while preserving native errors."
54    );
55    fallible_query!(
56        try_pivot,
57        ocio_exposure_contrast_transform_get_pivot,
58        f64,
59        "Read pivot while preserving native errors."
60    );
61    fallible_query!(
62        try_log_exposure_step,
63        ocio_exposure_contrast_transform_get_log_exposure_step,
64        f64,
65        "Read log exposure step while preserving native errors."
66    );
67    fallible_query!(
68        try_log_mid_gray,
69        ocio_exposure_contrast_transform_get_log_mid_gray,
70        f64,
71        "Read log mid-gray while preserving native errors."
72    );
73    fallible_query!(
74        try_is_exposure_dynamic,
75        ocio_exposure_contrast_transform_is_exposure_dynamic,
76        bool,
77        "Read the dynamic exposure flag while preserving native errors."
78    );
79    fallible_query!(
80        try_is_contrast_dynamic,
81        ocio_exposure_contrast_transform_is_contrast_dynamic,
82        bool,
83        "Read the dynamic contrast flag while preserving native errors."
84    );
85    fallible_query!(
86        try_is_gamma_dynamic,
87        ocio_exposure_contrast_transform_is_gamma_dynamic,
88        bool,
89        "Read the dynamic gamma flag while preserving native errors."
90    );
91
92    /// Read the native style, rejecting native errors and unknown values.
93    pub fn try_style(&self) -> Result<ExposureContrastStyle> {
94        match self.try_query(ocio_sys::ocio_exposure_contrast_transform_get_style)? {
95            0 => Ok(ExposureContrastStyle::Linear),
96            1 => Ok(ExposureContrastStyle::Video),
97            2 => Ok(ExposureContrastStyle::Logarithmic),
98            value => Err(OcioError::ValidationFailed(format!(
99                "unknown exposure/contrast style {value}"
100            ))),
101        }
102    }
103
104    /// Create a new exposure-contrast transform.
105    pub fn create() -> Result<Self> {
106        crate::clear_last_error();
107        let handle = unsafe { ocio_sys::ocio_exposure_contrast_transform_create() };
108        crate::handle_result(handle).map(|handle| Self { handle })
109    }
110
111    /// Return the current exposure value.
112    pub fn exposure(&self) -> f64 {
113        unsafe { ocio_sys::ocio_exposure_contrast_transform_get_exposure(self.handle.as_ptr()) }
114    }
115
116    /// Set the exposure value.
117    pub fn set_exposure(&self, exposure: f64) {
118        self.try_set_exposure(exposure)
119            .expect("failed to set exposure");
120    }
121
122    /// Set exposure and surface any OCIO validation error.
123    pub fn try_set_exposure(&self, exposure: f64) -> Result<()> {
124        crate::clear_last_error();
125        unsafe {
126            ocio_sys::ocio_exposure_contrast_transform_set_exposure(self.handle.as_ptr(), exposure)
127        };
128        crate::ocio_call_status()
129    }
130
131    /// Return the current contrast value.
132    pub fn contrast(&self) -> f64 {
133        unsafe { ocio_sys::ocio_exposure_contrast_transform_get_contrast(self.handle.as_ptr()) }
134    }
135
136    /// Set the contrast value.
137    pub fn set_contrast(&self, contrast: f64) {
138        self.try_set_contrast(contrast)
139            .expect("failed to set contrast");
140    }
141
142    /// Set contrast and surface any OCIO validation error.
143    pub fn try_set_contrast(&self, contrast: f64) -> Result<()> {
144        crate::clear_last_error();
145        unsafe {
146            ocio_sys::ocio_exposure_contrast_transform_set_contrast(self.handle.as_ptr(), contrast)
147        };
148        crate::ocio_call_status()
149    }
150
151    /// Return the current gamma value.
152    pub fn gamma(&self) -> f64 {
153        unsafe { ocio_sys::ocio_exposure_contrast_transform_get_gamma(self.handle.as_ptr()) }
154    }
155
156    /// Set the gamma value.
157    pub fn set_gamma(&self, gamma: f64) {
158        self.try_set_gamma(gamma).expect("failed to set gamma");
159    }
160
161    /// Set gamma and surface any OCIO validation error.
162    pub fn try_set_gamma(&self, gamma: f64) -> Result<()> {
163        crate::clear_last_error();
164        unsafe {
165            ocio_sys::ocio_exposure_contrast_transform_set_gamma(self.handle.as_ptr(), gamma)
166        };
167        crate::ocio_call_status()
168    }
169
170    /// Return the current pivot value.
171    pub fn pivot(&self) -> f64 {
172        unsafe { ocio_sys::ocio_exposure_contrast_transform_get_pivot(self.handle.as_ptr()) }
173    }
174
175    /// Set the pivot value.
176    pub fn set_pivot(&self, pivot: f64) {
177        self.try_set_pivot(pivot).expect("failed to set pivot");
178    }
179
180    /// Set pivot and surface any OCIO validation error.
181    pub fn try_set_pivot(&self, pivot: f64) -> Result<()> {
182        crate::clear_last_error();
183        unsafe {
184            ocio_sys::ocio_exposure_contrast_transform_set_pivot(self.handle.as_ptr(), pivot)
185        };
186        crate::ocio_call_status()
187    }
188
189    /// Return the current exposure-contrast style.
190    pub fn style(&self) -> ExposureContrastStyle {
191        let s =
192            unsafe { ocio_sys::ocio_exposure_contrast_transform_get_style(self.handle.as_ptr()) };
193        match s {
194            1 => ExposureContrastStyle::Video,
195            2 => ExposureContrastStyle::Logarithmic,
196            _ => ExposureContrastStyle::Linear,
197        }
198    }
199
200    /// Set the exposure-contrast style.
201    pub fn set_style(&self, style: ExposureContrastStyle) {
202        self.try_set_style(style)
203            .expect("failed to set exposure contrast style");
204    }
205
206    /// Set the exposure/contrast style and surface any OCIO validation error.
207    pub fn try_set_style(&self, style: ExposureContrastStyle) -> Result<()> {
208        crate::clear_last_error();
209        unsafe {
210            ocio_sys::ocio_exposure_contrast_transform_set_style(
211                self.handle.as_ptr(),
212                style as i32,
213            );
214        }
215        crate::ocio_call_status()
216    }
217
218    /// Return whether exposure is marked as dynamic.
219    pub fn is_exposure_dynamic(&self) -> bool {
220        unsafe {
221            ocio_sys::ocio_exposure_contrast_transform_is_exposure_dynamic(self.handle.as_ptr())
222        }
223    }
224
225    /// Mark exposure as dynamic.
226    pub fn make_exposure_dynamic(&self) {
227        self.try_make_exposure_dynamic()
228            .expect("failed to make exposure dynamic");
229    }
230
231    /// Mark exposure as dynamic and surface any OCIO validation error.
232    pub fn try_make_exposure_dynamic(&self) -> Result<()> {
233        crate::clear_last_error();
234        unsafe {
235            ocio_sys::ocio_exposure_contrast_transform_make_exposure_dynamic(self.handle.as_ptr())
236        };
237        crate::ocio_call_status()
238    }
239
240    /// Return whether contrast is marked as dynamic.
241    pub fn is_contrast_dynamic(&self) -> bool {
242        unsafe {
243            ocio_sys::ocio_exposure_contrast_transform_is_contrast_dynamic(self.handle.as_ptr())
244        }
245    }
246
247    /// Mark contrast as dynamic.
248    pub fn make_contrast_dynamic(&self) {
249        self.try_make_contrast_dynamic()
250            .expect("failed to make contrast dynamic");
251    }
252
253    /// Mark contrast as dynamic and surface any OCIO validation error.
254    pub fn try_make_contrast_dynamic(&self) -> Result<()> {
255        crate::clear_last_error();
256        unsafe {
257            ocio_sys::ocio_exposure_contrast_transform_make_contrast_dynamic(self.handle.as_ptr())
258        };
259        crate::ocio_call_status()
260    }
261
262    /// Mark exposure as non-dynamic.
263    pub fn make_exposure_non_dynamic(&self) {
264        self.try_make_exposure_non_dynamic()
265            .expect("failed to make exposure non-dynamic");
266    }
267
268    /// Mark exposure as non-dynamic and surface any OCIO validation error.
269    pub fn try_make_exposure_non_dynamic(&self) -> Result<()> {
270        crate::clear_last_error();
271        unsafe {
272            ocio_sys::ocio_exposure_contrast_transform_make_exposure_non_dynamic(
273                self.handle.as_ptr(),
274            )
275        };
276        crate::ocio_call_status()
277    }
278
279    /// Mark contrast as non-dynamic.
280    pub fn make_contrast_non_dynamic(&self) {
281        self.try_make_contrast_non_dynamic()
282            .expect("failed to make contrast non-dynamic");
283    }
284
285    /// Mark contrast as non-dynamic and surface any OCIO validation error.
286    pub fn try_make_contrast_non_dynamic(&self) -> Result<()> {
287        crate::clear_last_error();
288        unsafe {
289            ocio_sys::ocio_exposure_contrast_transform_make_contrast_non_dynamic(
290                self.handle.as_ptr(),
291            )
292        };
293        crate::ocio_call_status()
294    }
295
296    /// Return whether gamma is marked as dynamic.
297    pub fn is_gamma_dynamic(&self) -> bool {
298        unsafe { ocio_sys::ocio_exposure_contrast_transform_is_gamma_dynamic(self.handle.as_ptr()) }
299    }
300
301    /// Mark gamma as dynamic.
302    pub fn make_gamma_dynamic(&self) {
303        self.try_make_gamma_dynamic()
304            .expect("failed to make gamma dynamic");
305    }
306
307    /// Mark gamma as dynamic and surface any OCIO validation error.
308    pub fn try_make_gamma_dynamic(&self) -> Result<()> {
309        crate::clear_last_error();
310        unsafe {
311            ocio_sys::ocio_exposure_contrast_transform_make_gamma_dynamic(self.handle.as_ptr())
312        };
313        crate::ocio_call_status()
314    }
315
316    /// Mark gamma as non-dynamic.
317    pub fn make_gamma_non_dynamic(&self) {
318        self.try_make_gamma_non_dynamic()
319            .expect("failed to make gamma non-dynamic");
320    }
321
322    /// Mark gamma as non-dynamic and surface any OCIO validation error.
323    pub fn try_make_gamma_non_dynamic(&self) -> Result<()> {
324        crate::clear_last_error();
325        unsafe {
326            ocio_sys::ocio_exposure_contrast_transform_make_gamma_non_dynamic(self.handle.as_ptr())
327        };
328        crate::ocio_call_status()
329    }
330
331    /// Return the log exposure step value.
332    pub fn log_exposure_step(&self) -> f64 {
333        unsafe {
334            ocio_sys::ocio_exposure_contrast_transform_get_log_exposure_step(self.handle.as_ptr())
335        }
336    }
337
338    /// Set the log exposure step value.
339    pub fn set_log_exposure_step(&self, step: f64) {
340        self.try_set_log_exposure_step(step)
341            .expect("failed to set log exposure step");
342    }
343
344    /// Set the log exposure step and surface any OCIO validation error.
345    pub fn try_set_log_exposure_step(&self, step: f64) -> Result<()> {
346        crate::clear_last_error();
347        unsafe {
348            ocio_sys::ocio_exposure_contrast_transform_set_log_exposure_step(
349                self.handle.as_ptr(),
350                step,
351            )
352        };
353        crate::ocio_call_status()
354    }
355
356    /// Return the log mid-gray value.
357    pub fn log_mid_gray(&self) -> f64 {
358        unsafe { ocio_sys::ocio_exposure_contrast_transform_get_log_mid_gray(self.handle.as_ptr()) }
359    }
360
361    /// Set the log mid-gray value.
362    pub fn set_log_mid_gray(&self, mid_gray: f64) {
363        self.try_set_log_mid_gray(mid_gray)
364            .expect("failed to set log mid gray");
365    }
366
367    /// Set the log mid-gray value and surface any OCIO validation error.
368    pub fn try_set_log_mid_gray(&self, mid_gray: f64) -> Result<()> {
369        crate::clear_last_error();
370        unsafe {
371            ocio_sys::ocio_exposure_contrast_transform_set_log_mid_gray(
372                self.handle.as_ptr(),
373                mid_gray,
374            )
375        };
376        crate::ocio_call_status()
377    }
378
379    /// Return the transform direction.
380    pub fn direction(&self) -> TransformDirection {
381        let dir = unsafe {
382            ocio_sys::ocio_exposure_contrast_transform_get_direction(self.handle.as_ptr())
383        };
384        match dir {
385            1 => TransformDirection::Inverse,
386            _ => TransformDirection::Forward,
387        }
388    }
389
390    /// Set the transform direction.
391    pub fn set_direction(&self, direction: TransformDirection) {
392        self.try_set_direction(direction)
393            .expect("failed to set exposure-contrast transform direction");
394    }
395
396    /// Set the transform direction and surface any OCIO validation error.
397    pub fn try_set_direction(&self, direction: TransformDirection) -> crate::Result<()> {
398        crate::clear_last_error();
399        unsafe {
400            ocio_sys::ocio_exposure_contrast_transform_set_direction(
401                self.handle.as_ptr(),
402                direction as i32,
403            );
404        }
405        crate::ocio_call_status()
406    }
407
408    /// Create an independent copy of this transform.
409    pub fn create_editable_copy(&self) -> Result<Self> {
410        crate::clear_last_error();
411        let handle = unsafe { ocio_sys::ocio_transform_create_editable_copy(self.handle.as_ptr()) };
412        crate::handle_result(handle).map(|handle| Self { handle })
413    }
414
415    /// Return format metadata attached to the transform, when available.
416    pub fn format_metadata(&self) -> Option<crate::FormatMetadata> {
417        let handle = unsafe { ocio_sys::ocio_transform_get_format_metadata(self.handle.as_ptr()) };
418        NonNull::new(handle).map(|h| crate::FormatMetadata { handle: h })
419    }
420
421    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
422    pub fn format_metadata_v1(&self) -> Option<crate::FormatMetadata> {
423        self.format_metadata()
424    }
425
426    #[deprecated(since = "0.2.0", note = "compat alias; prefer format_metadata()")]
427    pub fn format_metadata_v2(&self) -> Option<crate::FormatMetadata> {
428        self.format_metadata()
429    }
430
431    /// Return whether this transform is equivalent to `other`.
432    pub fn equals(&self, other: &Self) -> bool {
433        unsafe {
434            ocio_sys::ocio_exposure_contrast_transform_equals(
435                self.handle.as_ptr(),
436                other.handle.as_ptr(),
437            )
438        }
439    }
440}
441
442impl Drop for ExposureContrastTransform {
443    fn drop(&mut self) {
444        unsafe { ocio_sys::ocio_exposure_contrast_transform_destroy(self.handle.as_ptr()) };
445    }
446}
447
448#[cfg(test)]
449mod tests {
450    use super::*;
451
452    #[test]
453    #[cfg(ocio_stub)]
454    fn fallible_queries_report_missing_native_backend() {
455        let transform = ExposureContrastTransform::create().unwrap();
456        assert!(transform.try_exposure().is_err());
457        assert!(transform.try_style().is_err());
458        assert!(transform.try_is_exposure_dynamic().is_err());
459    }
460
461    #[test]
462    fn create_exposure_contrast() {
463        let t = ExposureContrastTransform::create();
464        assert!(t.is_ok());
465    }
466
467    #[test]
468    fn exposure_contrast_methods_no_crash() {
469        let t = ExposureContrastTransform::create().unwrap();
470        let _ = t.exposure();
471        let _ = t.contrast();
472        let _ = t.gamma();
473        let _ = t.pivot();
474        let _ = t.style();
475        let _ = t.is_exposure_dynamic();
476        let _ = t.is_contrast_dynamic();
477        let _ = t.is_gamma_dynamic();
478    }
479
480    #[test]
481    fn set_values_no_crash() {
482        let t = ExposureContrastTransform::create().unwrap();
483        t.set_exposure(1.5);
484        t.set_contrast(1.2);
485        t.set_gamma(1.1);
486        t.set_pivot(0.18);
487        t.set_style(ExposureContrastStyle::Video);
488    }
489
490    #[test]
491    fn make_dynamic_no_crash() {
492        let t = ExposureContrastTransform::create().unwrap();
493        t.try_make_exposure_dynamic().unwrap();
494        t.try_make_contrast_dynamic().unwrap();
495        t.try_make_gamma_dynamic().unwrap();
496        t.try_make_exposure_non_dynamic().unwrap();
497        t.try_make_contrast_non_dynamic().unwrap();
498        t.try_make_gamma_non_dynamic().unwrap();
499        let _ = t.log_exposure_step();
500        t.set_log_exposure_step(0.088);
501        let _ = t.log_mid_gray();
502        t.set_log_mid_gray(0.18);
503    }
504
505    #[test]
506    fn direction_no_crash() {
507        let t = ExposureContrastTransform::create().unwrap();
508        let _ = t.direction();
509        t.set_direction(TransformDirection::Inverse);
510    }
511
512    #[test]
513    fn create_editable_copy_no_crash() {
514        let t = ExposureContrastTransform::create().unwrap();
515        let _ = t.create_editable_copy();
516    }
517
518    #[test]
519    fn format_metadata_no_crash() {
520        let t = ExposureContrastTransform::create().unwrap();
521        let _ = t.format_metadata();
522    }
523
524    #[test]
525    fn equals_no_crash() {
526        let a = ExposureContrastTransform::create().unwrap();
527        let b = ExposureContrastTransform::create().unwrap();
528        let _ = a.equals(&b);
529    }
530}