screencapturekit/stream/configuration/
captured_elements.rs

1//! Captured elements configuration
2//!
3//! Methods for configuring which elements are included in the capture
4//! (cursor, shadows, etc.).
5
6use super::internal::SCStreamConfiguration;
7#[cfg(feature = "macos_14_0")]
8use crate::error::{SCError, SCResult};
9
10impl SCStreamConfiguration {
11    /// Show or hide the cursor in captured frames
12    ///
13    /// # Examples
14    ///
15    /// ```
16    /// use screencapturekit::prelude::*;
17    ///
18    /// let mut config = SCStreamConfiguration::default();
19    /// config.set_shows_cursor(true);
20    /// assert!(config.shows_cursor());
21    /// ```
22    pub fn set_shows_cursor(&mut self, shows_cursor: bool) -> &mut Self {
23        unsafe {
24            crate::ffi::sc_stream_configuration_set_shows_cursor(self.as_ptr(), shows_cursor);
25        }
26        self
27    }
28
29    /// Show or hide the cursor (builder pattern)
30    #[must_use]
31    pub fn with_shows_cursor(mut self, shows_cursor: bool) -> Self {
32        self.set_shows_cursor(shows_cursor);
33        self
34    }
35
36    /// Check if cursor is shown in capture
37    pub fn shows_cursor(&self) -> bool {
38        unsafe { crate::ffi::sc_stream_configuration_get_shows_cursor(self.as_ptr()) }
39    }
40
41    /// Show mouse click indicators (macOS 15.0+)
42    ///
43    /// When enabled, draws a circle around the cursor when clicked.
44    /// This helps viewers track mouse activity in recordings.
45    ///
46    /// # Availability
47    /// macOS 15.0+. On earlier versions it returns
48    /// [`SCError::FeatureNotAvailable`].
49    ///
50    /// # Examples
51    /// ```
52    /// use screencapturekit::prelude::*;
53    ///
54    /// let config = SCStreamConfiguration::new()
55    ///     .with_shows_cursor(true)
56    ///     .with_shows_mouse_clicks(true)
57    ///     .expect("macOS 15.0 or later");
58    /// ```
59    #[cfg(feature = "macos_15_0")]
60    #[allow(clippy::missing_errors_doc)]
61    pub fn set_shows_mouse_clicks(&mut self, shows_mouse_clicks: bool) -> SCResult<&mut Self> {
62        let applied = unsafe {
63            crate::ffi::sc_stream_configuration_set_shows_mouse_clicks(
64                self.as_ptr(),
65                shows_mouse_clicks,
66            )
67        };
68        applied.then_some(self).ok_or_else(|| {
69            SCError::feature_not_available("SCStreamConfiguration.showMouseClicks", "15.0")
70        })
71    }
72
73    /// Show mouse click indicators (builder pattern)
74    #[cfg(feature = "macos_15_0")]
75    #[allow(clippy::missing_errors_doc)]
76    pub fn with_shows_mouse_clicks(mut self, shows_mouse_clicks: bool) -> SCResult<Self> {
77        self.set_shows_mouse_clicks(shows_mouse_clicks)?;
78        Ok(self)
79    }
80
81    /// Check if mouse click indicators are shown (macOS 15.0+)
82    #[cfg(feature = "macos_15_0")]
83    pub fn shows_mouse_clicks(&self) -> bool {
84        unsafe { crate::ffi::sc_stream_configuration_get_shows_mouse_clicks(self.as_ptr()) }
85    }
86
87    /// Capture only window shadows (macOS 14.0+)
88    ///
89    /// When set to `true`, the stream captures only the shadows of windows,
90    /// not the actual window content. This is useful for creating transparency
91    /// or blur effects in compositing applications.
92    ///
93    /// # Availability
94    /// macOS 14.0+. On earlier versions it returns
95    /// [`SCError::FeatureNotAvailable`].
96    ///
97    /// # Examples
98    /// ```no_run
99    /// use screencapturekit::prelude::*;
100    ///
101    /// let config = SCStreamConfiguration::new()
102    ///     .with_width(1920)
103    ///     .with_height(1080)
104    ///     .with_captures_shadows_only(true)
105    ///     .expect("macOS 14.0 or later");
106    /// ```
107    #[cfg(feature = "macos_14_0")]
108    #[allow(clippy::missing_errors_doc)]
109    pub fn set_captures_shadows_only(
110        &mut self,
111        captures_shadows_only: bool,
112    ) -> SCResult<&mut Self> {
113        let applied = unsafe {
114            crate::ffi::sc_stream_configuration_set_captures_shadows_only(
115                self.as_ptr(),
116                captures_shadows_only,
117            )
118        };
119        applied.then_some(self).ok_or_else(|| {
120            SCError::feature_not_available("SCStreamConfiguration.capturesShadowsOnly", "14.0")
121        })
122    }
123
124    /// Capture only window shadows (builder pattern)
125    #[cfg(feature = "macos_14_0")]
126    #[allow(clippy::missing_errors_doc)]
127    pub fn with_captures_shadows_only(mut self, captures_shadows_only: bool) -> SCResult<Self> {
128        self.set_captures_shadows_only(captures_shadows_only)?;
129        Ok(self)
130    }
131
132    /// Get whether only window shadows are captured (macOS 14.0+).
133    #[cfg(feature = "macos_14_0")]
134    pub fn captures_shadows_only(&self) -> bool {
135        unsafe { crate::ffi::sc_stream_configuration_get_captures_shadows_only(self.as_ptr()) }
136    }
137
138    /// Ignore shadows for display capture (macOS 14.0+)
139    ///
140    /// When set to `true`, window shadows are excluded from display capture.
141    ///
142    /// # Availability
143    /// macOS 14.0+. On earlier versions it returns
144    /// [`SCError::FeatureNotAvailable`].
145    #[cfg(feature = "macos_14_0")]
146    #[allow(clippy::missing_errors_doc)]
147    pub fn set_ignores_shadows_display(&mut self, ignores_shadows: bool) -> SCResult<&mut Self> {
148        let applied = unsafe {
149            crate::ffi::sc_stream_configuration_set_ignores_shadows_display(
150                self.as_ptr(),
151                ignores_shadows,
152            )
153        };
154        applied.then_some(self).ok_or_else(|| {
155            SCError::feature_not_available("SCStreamConfiguration.ignoreShadowsDisplay", "14.0")
156        })
157    }
158
159    /// Ignore shadows for display capture (builder pattern)
160    #[cfg(feature = "macos_14_0")]
161    #[allow(clippy::missing_errors_doc)]
162    pub fn with_ignores_shadows_display(mut self, ignores_shadows: bool) -> SCResult<Self> {
163        self.set_ignores_shadows_display(ignores_shadows)?;
164        Ok(self)
165    }
166
167    /// Check if shadows are ignored for display capture (macOS 14.0+)
168    #[cfg(feature = "macos_14_0")]
169    pub fn ignores_shadows_display(&self) -> bool {
170        unsafe { crate::ffi::sc_stream_configuration_get_ignores_shadows_display(self.as_ptr()) }
171    }
172
173    /// Ignore global clip for display capture (macOS 14.0+)
174    ///
175    /// When set to `true`, the global clip region is ignored for display capture.
176    ///
177    /// # Availability
178    /// macOS 14.0+. On earlier versions it returns
179    /// [`SCError::FeatureNotAvailable`].
180    #[cfg(feature = "macos_14_0")]
181    #[allow(clippy::missing_errors_doc)]
182    pub fn set_ignore_global_clip_display(&mut self, ignore: bool) -> SCResult<&mut Self> {
183        let applied = unsafe {
184            crate::ffi::sc_stream_configuration_set_ignore_global_clip_display(
185                self.as_ptr(),
186                ignore,
187            )
188        };
189        applied.then_some(self).ok_or_else(|| {
190            SCError::feature_not_available("SCStreamConfiguration.ignoreGlobalClipDisplay", "14.0")
191        })
192    }
193
194    /// Ignore global clip for display capture (builder pattern)
195    #[cfg(feature = "macos_14_0")]
196    #[allow(clippy::missing_errors_doc)]
197    pub fn with_ignore_global_clip_display(mut self, ignore: bool) -> SCResult<Self> {
198        self.set_ignore_global_clip_display(ignore)?;
199        Ok(self)
200    }
201
202    /// Check if global clip is ignored for display capture (macOS 14.0+)
203    #[cfg(feature = "macos_14_0")]
204    pub fn ignore_global_clip_display(&self) -> bool {
205        unsafe { crate::ffi::sc_stream_configuration_get_ignore_global_clip_display(self.as_ptr()) }
206    }
207
208    /// Ignore global clip for single window capture (macOS 14.0+)
209    ///
210    /// When set to `true`, the global clip region is ignored for single window capture.
211    ///
212    /// # Availability
213    /// macOS 14.0+. On earlier versions it returns
214    /// [`SCError::FeatureNotAvailable`].
215    #[cfg(feature = "macos_14_0")]
216    #[allow(clippy::missing_errors_doc)]
217    pub fn set_ignore_global_clip_single_window(&mut self, ignore: bool) -> SCResult<&mut Self> {
218        let applied = unsafe {
219            crate::ffi::sc_stream_configuration_set_ignore_global_clip_single_window(
220                self.as_ptr(),
221                ignore,
222            )
223        };
224        applied.then_some(self).ok_or_else(|| {
225            SCError::feature_not_available(
226                "SCStreamConfiguration.ignoreGlobalClipSingleWindow",
227                "14.0",
228            )
229        })
230    }
231
232    /// Ignore global clip for single window capture (builder pattern)
233    #[cfg(feature = "macos_14_0")]
234    #[allow(clippy::missing_errors_doc)]
235    pub fn with_ignore_global_clip_single_window(mut self, ignore: bool) -> SCResult<Self> {
236        self.set_ignore_global_clip_single_window(ignore)?;
237        Ok(self)
238    }
239
240    /// Check if global clip is ignored for single window capture (macOS 14.0+)
241    #[cfg(feature = "macos_14_0")]
242    pub fn ignore_global_clip_single_window(&self) -> bool {
243        unsafe {
244            crate::ffi::sc_stream_configuration_get_ignore_global_clip_single_window(self.as_ptr())
245        }
246    }
247}
screencapturekit/stream/configuration/captured_elements.rs

screencapturekit/stream/configuration/
captured_elements.rs
