Skip to main content

ocio_rs/
format_metadata.rs

1use std::ffi::c_void;
2use std::ptr::NonNull;
3
4use crate::{cstr_from_mut, cstr_to_opt_string, cstring, Result};
5use ocio_sys;
6
7fn stream_metadata(handle: NonNull<c_void>, is_const: bool) -> Result<String> {
8    crate::clear_last_error();
9    let ptr = unsafe { ocio_sys::ocio_format_metadata_stream(handle.as_ptr(), is_const) };
10    crate::ocio_call_status()?;
11    unsafe { cstr_to_opt_string(ptr) }.ok_or_else(|| {
12        crate::OcioError::ValidationFailed("native metadata stream returned null".into())
13    })
14}
15
16/// Structured metadata attached to transforms and baked outputs.
17pub struct FormatMetadata {
18    pub(crate) handle: NonNull<c_void>,
19}
20
21/// Shared read-only metadata retained by an OCIO processor or transform.
22///
23/// Child handles retain the native owner. Borrowed text remains valid while
24/// this handle is alive, absent external native mutation. Metadata supplied
25/// by [`crate::transform::ConstTransform::with_readonly_metadata`] is additionally
26/// subject to that callback's scope and aliasing safety requirements.
27pub struct ConstFormatMetadata {
28    pub(crate) handle: NonNull<c_void>,
29}
30impl ConstFormatMetadata {
31    /// Format metadata using OCIO's native stream operator. This is diagnostic
32    /// text, not an XML serializer, and is copied into a Rust-owned string.
33    pub fn to_native_string(&self) -> Result<String> {
34        stream_metadata(self.handle, true)
35    }
36    fn text(
37        &self,
38        field: i32,
39        index: i32,
40        name: Option<&std::ffi::CStr>,
41    ) -> Result<Option<&std::ffi::CStr>> {
42        crate::clear_last_error();
43        let ptr = unsafe {
44            ocio_sys::ocio_const_format_metadata_text(
45                self.handle.as_ptr(),
46                field,
47                index,
48                name.map_or(std::ptr::null(), |v| v.as_ptr()),
49            )
50        };
51        crate::ocio_call_status()?;
52        Ok(if ptr.is_null() {
53            None
54        } else {
55            Some(unsafe { std::ffi::CStr::from_ptr(ptr) })
56        })
57    }
58    fn count(&self, children: bool) -> Result<i32> {
59        crate::clear_last_error();
60        let value =
61            unsafe { ocio_sys::ocio_const_format_metadata_count(self.handle.as_ptr(), children) };
62        crate::ocio_call_status()?;
63        Ok(value)
64    }
65    /// Borrow the element name.
66    pub fn element_name(&self) -> Result<Option<&std::ffi::CStr>> {
67        self.text(0, 0, None)
68    }
69    /// Borrow the element value.
70    pub fn element_value(&self) -> Result<Option<&std::ffi::CStr>> {
71        self.text(1, 0, None)
72    }
73    /// Borrow the name attribute.
74    pub fn name(&self) -> Result<Option<&std::ffi::CStr>> {
75        self.text(2, 0, None)
76    }
77    /// Borrow the ID attribute.
78    pub fn id(&self) -> Result<Option<&std::ffi::CStr>> {
79        self.text(3, 0, None)
80    }
81    /// Number of attributes.
82    pub fn num_attributes(&self) -> Result<i32> {
83        self.count(false)
84    }
85    /// Borrow an attribute name by index.
86    pub fn attribute_name(&self, index: i32) -> Result<Option<&std::ffi::CStr>> {
87        self.text(4, index, None)
88    }
89    /// Borrow an attribute value by index.
90    pub fn attribute_value_by_index(&self, index: i32) -> Result<Option<&std::ffi::CStr>> {
91        self.text(5, index, None)
92    }
93    /// Borrow an attribute value by name.
94    pub fn attribute_value(&self, name: &std::ffi::CStr) -> Result<Option<&std::ffi::CStr>> {
95        self.text(6, 0, Some(name))
96    }
97    /// Number of child elements.
98    pub fn num_children(&self) -> Result<i32> {
99        self.count(true)
100    }
101    /// Share a child; invalid indices preserve native errors.
102    pub fn child(&self, index: i32) -> Result<Option<Self>> {
103        crate::clear_last_error();
104        let handle =
105            unsafe { ocio_sys::ocio_const_format_metadata_child(self.handle.as_ptr(), index) };
106        crate::ocio_call_status()?;
107        Ok(NonNull::new(handle).map(|handle| Self { handle }))
108    }
109    /// Create a deep, independently editable metadata copy.
110    pub fn create_editable_copy(&self) -> Result<FormatMetadata> {
111        crate::clear_last_error();
112        let handle = unsafe { ocio_sys::ocio_const_format_metadata_copy(self.handle.as_ptr()) };
113        crate::handle_result(handle).map(|handle| FormatMetadata { handle })
114    }
115}
116impl Drop for ConstFormatMetadata {
117    fn drop(&mut self) {
118        unsafe { ocio_sys::ocio_const_format_metadata_destroy(self.handle.as_ptr()) }
119    }
120}
121
122impl FormatMetadata {
123    /// Format metadata using OCIO's native stream operator. This is diagnostic
124    /// text, not an XML serializer, and is copied into a Rust-owned string.
125    pub fn to_native_string(&self) -> Result<String> {
126        stream_metadata(self.handle, false)
127    }
128    fn read_text(
129        &self,
130        read: impl FnOnce(*mut c_void) -> *const std::ffi::c_char,
131    ) -> Result<Option<String>> {
132        crate::clear_last_error();
133        let value = unsafe { cstr_to_opt_string(read(self.handle.as_ptr())) };
134        crate::ocio_call_status()?;
135        Ok(value)
136    }
137
138    fn read_count(&self, read: impl FnOnce(*mut c_void) -> i32) -> Result<i32> {
139        crate::clear_last_error();
140        let value = read(self.handle.as_ptr());
141        crate::ocio_call_status()?;
142        Ok(value)
143    }
144
145    /// Get the element name.
146    pub fn element_name(&self) -> Option<String> {
147        self.try_element_name().ok().flatten()
148    }
149
150    /// Get the element name, reporting an invalidated handle.
151    pub fn try_element_name(&self) -> Result<Option<String>> {
152        self.read_text(|handle| unsafe { ocio_sys::ocio_format_metadata_get_element_name(handle) })
153    }
154
155    /// Set the element name.
156    pub fn set_element_name(&self, name: impl AsRef<str>) -> Result<()> {
157        let name = cstring(name)?;
158        crate::clear_last_error();
159        unsafe {
160            ocio_sys::ocio_format_metadata_set_element_name(
161                self.handle.as_ptr(),
162                name.as_ptr().cast(),
163            )
164        };
165        crate::ocio_call_status()
166    }
167
168    /// Get the element value.
169    pub fn element_value(&self) -> Option<String> {
170        self.try_element_value().ok().flatten()
171    }
172
173    /// Get the element value, reporting an invalidated handle.
174    pub fn try_element_value(&self) -> Result<Option<String>> {
175        self.read_text(|handle| unsafe { ocio_sys::ocio_format_metadata_get_element_value(handle) })
176    }
177
178    /// Set the element value.
179    pub fn set_element_value(&self, value: impl AsRef<str>) -> Result<()> {
180        let v = cstring(value)?;
181        crate::clear_last_error();
182        unsafe {
183            ocio_sys::ocio_format_metadata_set_element_value(
184                self.handle.as_ptr(),
185                v.as_ptr().cast(),
186            )
187        };
188        crate::ocio_call_status()
189    }
190
191    /// Get the number of attributes on this metadata element.
192    pub fn num_attributes(&self) -> i32 {
193        self.try_num_attributes().unwrap_or_default()
194    }
195
196    /// Get the attribute count, reporting an invalidated handle.
197    pub fn try_num_attributes(&self) -> Result<i32> {
198        self.read_count(|handle| unsafe {
199            ocio_sys::ocio_format_metadata_get_num_attributes(handle)
200        })
201    }
202
203    /// Get the attribute name at the given index.
204    pub fn attribute_name(&self, i: i32) -> Option<String> {
205        self.try_attribute_name(i).ok().flatten()
206    }
207
208    /// Get an attribute name, reporting an invalidated handle.
209    pub fn try_attribute_name(&self, i: i32) -> Result<Option<String>> {
210        self.read_text(|handle| unsafe {
211            ocio_sys::ocio_format_metadata_get_attribute_name(handle, i)
212        })
213    }
214
215    /// Get the attribute value at the given index.
216    pub fn attribute_value_by_index(&self, i: i32) -> Option<String> {
217        self.try_attribute_value_by_index(i).ok().flatten()
218    }
219
220    /// Get an attribute value by index, preserving OCIO query failures.
221    pub fn try_attribute_value_by_index(&self, i: i32) -> Result<Option<String>> {
222        crate::clear_last_error();
223        let value = unsafe {
224            cstr_to_opt_string(ocio_sys::ocio_format_metadata_get_attribute_value_by_index(
225                self.handle.as_ptr(),
226                i,
227            ))
228        };
229        crate::ocio_call_status()?;
230        Ok(value)
231    }
232
233    /// Get the attribute value by name.
234    pub fn attribute_value(&self, name: impl AsRef<str>) -> Option<String> {
235        self.try_attribute_value(name).ok().flatten()
236    }
237
238    /// Get an attribute value by name, preserving invalid input and OCIO failures.
239    pub fn try_attribute_value(&self, name: impl AsRef<str>) -> Result<Option<String>> {
240        let n = cstring(name)?;
241        crate::clear_last_error();
242        let value = unsafe {
243            cstr_to_opt_string(ocio_sys::ocio_format_metadata_get_attribute_value(
244                self.handle.as_ptr(),
245                n.as_ptr().cast(),
246            ))
247        };
248        crate::ocio_call_status()?;
249        Ok(value)
250    }
251
252    /// Add a name-value attribute to this metadata element.
253    pub fn add_attribute(&self, name: impl AsRef<str>, value: impl AsRef<str>) -> Result<()> {
254        let n = cstring(name)?;
255        let v = cstring(value)?;
256        crate::clear_last_error();
257        unsafe {
258            ocio_sys::ocio_format_metadata_add_attribute(
259                self.handle.as_ptr(),
260                n.as_ptr().cast(),
261                v.as_ptr().cast(),
262            )
263        };
264        crate::ocio_call_status()
265    }
266
267    /// Get the number of child elements.
268    pub fn num_children(&self) -> i32 {
269        self.try_num_children().unwrap_or_default()
270    }
271
272    /// Get the child count, reporting an invalidated handle.
273    pub fn try_num_children(&self) -> Result<i32> {
274        self.read_count(|handle| unsafe {
275            ocio_sys::ocio_format_metadata_get_num_children_elements(handle)
276        })
277    }
278
279    /// Get a live child element at the given index.
280    ///
281    /// The wrapper remains usable when siblings are appended. Clearing an
282    /// ancestor invalidates it: subsequent fallible operations return an error
283    /// even if a new child later occupies the same index.
284    pub fn child_element(&self, i: i32) -> Option<FormatMetadata> {
285        self.try_child_element(i).ok().flatten()
286    }
287
288    /// Get a live child element by index, preserving OCIO query failures.
289    ///
290    /// See [`Self::child_element`] for invalidation behavior.
291    pub fn try_child_element(&self, i: i32) -> Result<Option<FormatMetadata>> {
292        crate::clear_last_error();
293        let handle =
294            unsafe { ocio_sys::ocio_format_metadata_get_child_element(self.handle.as_ptr(), i) };
295        crate::ocio_call_status()?;
296        Ok(NonNull::new(handle).map(|handle| FormatMetadata { handle }))
297    }
298
299    /// Add a child element with the given name and value.
300    pub fn add_child_element(&self, name: impl AsRef<str>, value: impl AsRef<str>) -> Result<()> {
301        let n = cstring(name)?;
302        let v = cstring(value)?;
303        crate::clear_last_error();
304        unsafe {
305            ocio_sys::ocio_format_metadata_add_child_element(
306                self.handle.as_ptr(),
307                n.as_ptr().cast(),
308                v.as_ptr().cast(),
309            )
310        };
311        crate::ocio_call_status()
312    }
313
314    /// Clear all data on this metadata element.
315    pub fn clear(&self) {
316        let _ = self.try_clear();
317    }
318
319    /// Clear this element and invalidate all previously obtained descendants.
320    pub fn try_clear(&self) -> Result<()> {
321        crate::clear_last_error();
322        unsafe { ocio_sys::ocio_format_metadata_clear(self.handle.as_ptr() as *mut c_void) };
323        crate::ocio_call_status()
324    }
325
326    /// Replace this element with a deep copy of `source`, matching native
327    /// metadata assignment. Existing descendants of this element are
328    /// invalidated, including if native assignment fails after it begins.
329    /// Assigning an element to itself is a no-op. Overlapping source and
330    /// destination trees are supported by snapshotting the source first.
331    pub fn assign(&self, source: &FormatMetadata) -> Result<()> {
332        crate::clear_last_error();
333        unsafe {
334            ocio_sys::ocio_format_metadata_assign(self.handle.as_ptr(), source.handle.as_ptr())
335        };
336        crate::ocio_call_status()
337    }
338
339    /// Replace this element with a copy of processor-owned read-only metadata.
340    ///
341    /// This copies directly from the native processor metadata without first
342    /// creating an editable intermediate. Existing descendants are invalidated
343    /// before assignment, including if native assignment subsequently fails.
344    pub fn assign_const(&self, source: &ConstFormatMetadata) -> Result<()> {
345        crate::clear_last_error();
346        unsafe {
347            ocio_sys::ocio_format_metadata_assign_const(
348                self.handle.as_ptr(),
349                source.handle.as_ptr(),
350            )
351        };
352        crate::ocio_call_status()
353    }
354
355    /// Get the name of this metadata element.
356    pub fn name(&self) -> Option<String> {
357        self.try_name().ok().flatten()
358    }
359
360    /// Get the name attribute, reporting an invalidated handle.
361    pub fn try_name(&self) -> Result<Option<String>> {
362        self.read_text(|handle| unsafe { ocio_sys::ocio_format_metadata_get_name(handle) })
363    }
364
365    /// Set the name of this metadata element.
366    pub fn set_name(&self, name: impl AsRef<str>) -> Result<()> {
367        let n = cstring(name)?;
368        crate::clear_last_error();
369        unsafe { ocio_sys::ocio_format_metadata_set_name(self.handle.as_ptr(), n.as_ptr().cast()) };
370        crate::ocio_call_status()
371    }
372
373    /// Get the ID of this metadata element.
374    pub fn id(&self) -> Option<String> {
375        self.try_id().ok().flatten()
376    }
377
378    /// Get the ID attribute, reporting an invalidated handle.
379    pub fn try_id(&self) -> Result<Option<String>> {
380        self.read_text(|handle| unsafe { ocio_sys::ocio_format_metadata_get_id(handle) })
381    }
382
383    /// Set the ID of this metadata element.
384    pub fn set_id(&self, id: impl AsRef<str>) -> Result<()> {
385        let i = cstring(id)?;
386        crate::clear_last_error();
387        unsafe { ocio_sys::ocio_format_metadata_set_id(self.handle.as_ptr(), i.as_ptr().cast()) };
388        crate::ocio_call_status()
389    }
390}
391
392impl Drop for FormatMetadata {
393    fn drop(&mut self) {
394        unsafe { ocio_sys::ocio_format_metadata_destroy(self.handle.as_ptr() as *mut c_void) };
395    }
396}
397
398#[cfg(test)]
399mod tests {
400    use crate::Baker;
401
402    #[test]
403    fn format_metadata_from_baker_no_crash() {
404        let baker = Baker::create().unwrap();
405        let md = baker.format_metadata();
406        if let Some(md) = md {
407            let _ = md.element_name();
408            let _ = md.element_value();
409            let _ = md.num_attributes();
410            let _ = md.attribute_name(0);
411            let _ = md.attribute_value_by_index(0);
412            let _ = md.attribute_value("key");
413            let _ = md.num_children();
414            let _ = md.child_element(0);
415            let _ = md.name();
416            let _ = md.id();
417        }
418    }
419
420    #[test]
421    fn format_metadata_setters_no_crash() {
422        let baker = Baker::create().unwrap();
423        let md = baker.format_metadata();
424        if let Some(md) = md {
425            let _ = md.set_element_name("TestElement");
426            let _ = md.set_element_value("TestValue");
427            let _ = md.add_attribute("attr1", "val1");
428            let _ = md.add_child_element("child", "value");
429            md.clear();
430            let _ = md.set_name("TestName");
431            let _ = md.set_id("TestID");
432        }
433    }
434
435    #[test]
436    fn format_metadata_attribute_by_name_no_crash() {
437        let baker = Baker::create().unwrap();
438        let md = baker.format_metadata();
439        if let Some(md) = md {
440            let _ = md.set_element_name("elem");
441            let _ = md.attribute_value("nonexistent_key");
442        }
443    }
444
445    #[test]
446    fn format_metadata_child_element_no_crash() {
447        let baker = Baker::create().unwrap();
448        let md = baker.format_metadata();
449        if let Some(md) = md {
450            let child = md.child_element(0);
451            if let Some(child) = child {
452                let _ = child.element_name();
453                let _ = child.element_value();
454            }
455        }
456    }
457
458    #[test]
459    fn format_metadata_name_id_no_crash() {
460        let baker = Baker::create().unwrap();
461        let md = baker.format_metadata();
462        if let Some(md) = md {
463            let _ = md.name();
464            let _ = md.id();
465            let _ = md.set_name("MyName");
466            let _ = md.set_id("MyID");
467        }
468    }
469}