screencapturekit/stream/configuration/
stream_properties.rs

1//! Stream identification and HDR configuration
2//!
3//! This module provides methods to configure stream identification and HDR capture settings.
4
5use super::internal::SCStreamConfiguration;
6use crate::utils::ffi_string::{ffi_string_from_buffer, SMALL_BUFFER_SIZE};
7
8/// Dynamic range mode for capture (macOS 15.0+)
9#[repr(i32)]
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
11pub enum SCCaptureDynamicRange {
12    /// Standard Dynamic Range (SDR) - default mode
13    #[default]
14    SDR = 0,
15    /// HDR with local display tone mapping
16    HDRLocalDisplay = 1,
17    /// HDR with canonical display tone mapping
18    HDRCanonicalDisplay = 2,
19}
20
21impl SCStreamConfiguration {
22    /// Set the stream name for identification
23    ///
24    /// Assigns a name to the stream that can be used for debugging and identification
25    /// purposes. The name appears in system logs and debugging tools.
26    ///
27    /// # Examples
28    ///
29    /// ```rust,no_run
30    /// use screencapturekit::prelude::*;
31    ///
32    /// let config = SCStreamConfiguration::new()
33    ///     .with_stream_name(Some("MyApp-MainCapture"));
34    /// ```
35    pub fn set_stream_name(&mut self, name: Option<&str>) -> &mut Self {
36        unsafe {
37            if let Some(stream_name) = name {
38                if let Ok(c_name) = std::ffi::CString::new(stream_name) {
39                    crate::ffi::sc_stream_configuration_set_stream_name(
40                        self.as_ptr(),
41                        c_name.as_ptr(),
42                    );
43                }
44            } else {
45                crate::ffi::sc_stream_configuration_set_stream_name(
46                    self.as_ptr(),
47                    std::ptr::null(),
48                );
49            }
50        }
51        self
52    }
53
54    /// Set the stream name (builder pattern)
55    #[must_use]
56    pub fn with_stream_name(mut self, name: Option<&str>) -> Self {
57        self.set_stream_name(name);
58        self
59    }
60
61    /// Get the configured stream name
62    ///
63    /// Returns the name assigned to this stream, if any.
64    pub fn stream_name(&self) -> Option<String> {
65        unsafe {
66            ffi_string_from_buffer(SMALL_BUFFER_SIZE, |buf, len| {
67                crate::ffi::sc_stream_configuration_get_stream_name(self.as_ptr(), buf, len)
68            })
69        }
70    }
71
72    /// Set the dynamic range mode for capture (macOS 15.0+)
73    ///
74    /// Controls whether to capture in SDR or HDR mode and how HDR content
75    /// should be tone-mapped for display.
76    ///
77    /// # Availability
78    /// macOS 15.0+. Requires the `macos_15_0` feature flag to be enabled.
79    ///
80    /// # Modes
81    /// - `SDR`: Standard dynamic range capture (default)
82    /// - `HDRLocalDisplay`: HDR with tone mapping optimized for the local display
83    /// - `HDRCanonicalDisplay`: HDR with canonical tone mapping for portability
84    ///
85    /// # Examples
86    ///
87    /// ```rust,no_run
88    /// use screencapturekit::prelude::*;
89    /// use screencapturekit::stream::configuration::stream_properties::SCCaptureDynamicRange;
90    ///
91    /// let config = SCStreamConfiguration::new()
92    ///     .with_width(1920)
93    ///     .with_height(1080)
94    ///     .with_capture_dynamic_range(SCCaptureDynamicRange::HDRLocalDisplay);
95    /// ```
96    #[cfg(feature = "macos_15_0")]
97    pub fn set_capture_dynamic_range(&mut self, dynamic_range: SCCaptureDynamicRange) -> &mut Self {
98        unsafe {
99            crate::ffi::sc_stream_configuration_set_capture_dynamic_range(
100                self.as_ptr(),
101                dynamic_range as i32,
102            );
103        }
104        self
105    }
106
107    /// Set the dynamic range mode (builder pattern)
108    #[cfg(feature = "macos_15_0")]
109    #[must_use]
110    pub fn with_capture_dynamic_range(mut self, dynamic_range: SCCaptureDynamicRange) -> Self {
111        self.set_capture_dynamic_range(dynamic_range);
112        self
113    }
114
115    /// Get the configured dynamic range mode (macOS 15.0+)
116    ///
117    /// Returns the current HDR capture mode setting.
118    ///
119    /// Requires the `macos_15_0` feature flag to be enabled.
120    #[cfg(feature = "macos_15_0")]
121    pub fn capture_dynamic_range(&self) -> SCCaptureDynamicRange {
122        let value =
123            unsafe { crate::ffi::sc_stream_configuration_get_capture_dynamic_range(self.as_ptr()) };
124        match value {
125            1 => SCCaptureDynamicRange::HDRLocalDisplay,
126            2 => SCCaptureDynamicRange::HDRCanonicalDisplay,
127            _ => SCCaptureDynamicRange::SDR,
128        }
129    }
130}
screencapturekit/stream/configuration/stream_properties.rs

screencapturekit/stream/configuration/
stream_properties.rs
