feat!: drop CGImage and CMTime duplicates, re-export from apple-cf

BREAKING CHANGE: ScreenshotManager::capture now returns apple_cf::cg::CGImage
(was a private nominal duplicate); screencapturekit::cm::CMTime is now a
re-export of apple_cf::cm::CMTime (was a private nominal duplicate). Both
changes eliminate cross-crate type conversions for downstream consumers
chaining ScreenCaptureKit -> ImageIO / VideoToolbox / etc.

Bumps version 3.1.4 -> 4.0.0.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 1313

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-05-18
+
+### Changed
+
+- [**breaking**] `ScreenshotManager::capture_image` now returns `apple_cf::cg::CGImage` (was a private nominal duplicate)
+- [**breaking**] `screencapturekit::cm::CMTime` is now a re-export of `apple_cf::cm::CMTime` (was a private nominal duplicate)
+- both changes eliminate cross-crate type conversions for downstream consumers chaining `ScreenCaptureKit` → `ImageIO` / `VideoToolbox` / related Apple frameworks
+
 ## [3.1.4] - 2026-05-17
 
 ### Fixed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "screencapturekit"
-version = "3.1.4"
+version = "4.0.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 homepage = "https://github.com/doom-fish/screencapturekit-rs"
@@ -66,7 +66,7 @@ macos_26_0 = ["macos_15_2"]
 # and Cargo's `[patch.crates-io]` will redirect to your sibling paths.
 # This lets `cargo install screencapturekit` and `release-plz` work from
 # a clean checkout without requiring the sibling repos.
-apple-cf = { version = ">=0.6, <0.8", default-features = false, features = ["cg", "iosurface", "dispatch", "cv", "cm"] }
+apple-cf = { version = ">=0.6, <0.9", default-features = false, features = ["cg", "iosurface", "dispatch", "cv", "cm"] }
 apple-metal = { version = ">=0.6, <0.9", default-features = false, features = ["iosurface"] }
 
 [dev-dependencies]

README.md

@@ -43,7 +43,7 @@
 
 ```toml
 [dependencies]
-screencapturekit = "3"
+screencapturekit = "4"
 ```
 
 Opt-in features (additive):
@@ -62,7 +62,7 @@ Opt-in features (additive):
 `macos_*` features are **cumulative** — enabling `macos_15_0` automatically enables every earlier version. Pick the highest version your minimum-supported macOS will satisfy:
 
 ```toml
-screencapturekit = { version = "3", features = ["async", "macos_15_0"] }
+screencapturekit = { version = "4", features = ["async", "macos_15_0"] }
 ```
 
 > **Upgrading from 1.x?** See [`docs/MIGRATION.md`](docs/MIGRATION.md#migrating-from-1x-to-20)
@@ -206,7 +206,7 @@ custom executor — the binding does **not** spawn its own runtime.
 #     filter: &screencapturekit::stream::content_filter::SCContentFilter,
 #     config: &screencapturekit::stream::configuration::SCStreamConfiguration,
 # ) -> Result<(), Box<dyn std::error::Error>> {
-use screencapturekit::screenshot_manager::SCScreenshotManager;
+use screencapturekit::screenshot_manager::{CGImageExt, SCScreenshotManager};
 
 let img = SCScreenshotManager::capture_image(filter, config)?;
 let pixels = img.bgra_data()?;            // native BGRA — skips R↔B swap
@@ -398,7 +398,7 @@ sampling profiler; nearly all CPU lives in Apple's `SkyLight` /
 **Hot-path tips:**
 
 - Prefer `BGRA` to skip the per-pixel R↔B swap when uploading to Metal /
-  wgpu / ffmpeg (`SCScreenshotManager::bgra_data` is ~5% faster than `rgba_data`).
+  wgpu / ffmpeg (`CGImageExt::bgra_data` is ~5% faster than `rgba_data`).
 - Reuse a `Vec<u8>` across screenshots with the `*_data_into` variants
   (saves a ~33 MB allocation per 4K frame — new in 2.1).
 - When iterating many windows / displays / apps, use the batched
@@ -461,7 +461,7 @@ The 2.0 highlights:
   dropping symbols)
 
 2.1 added the `bgra_data_into` / `rgba_data_into` buffer-reuse APIs and a
-native-BGRA fast path on `SCScreenshotManager` — both are non-breaking.
+native-BGRA fast path on captured `CGImage`s — both are non-breaking.
 
 ## Contributing
 

benches/hotspots.rs

@@ -11,6 +11,7 @@ use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
 use screencapturekit::cm::CMSampleBuffer;
 use screencapturekit::cv::CVPixelBufferLockFlags;
 use screencapturekit::prelude::*;
+use screencapturekit::screenshot_manager::CGImageExt;
 use screencapturekit::shareable_content::SCShareableContent;
 use screencapturekit::stream::configuration::SCStreamConfiguration;
 use screencapturekit::stream::content_filter::SCContentFilter;

examples/05_screenshot.rs

@@ -12,7 +12,7 @@
 #[cfg(feature = "macos_14_0")]
 use screencapturekit::prelude::*;
 #[cfg(feature = "macos_14_0")]
-use screencapturekit::screenshot_manager::SCScreenshotManager;
+use screencapturekit::screenshot_manager::{CGImageExt, SCScreenshotManager};
 
 #[cfg(not(feature = "macos_14_0"))]
 fn main() {

examples/22_tauri_app/src-tauri/src/lib.rs

@@ -5,7 +5,7 @@
 
 use base64::{engine::general_purpose::STANDARD, Engine};
 use screencapturekit::prelude::*;
-use screencapturekit::screenshot_manager::SCScreenshotManager;
+use screencapturekit::screenshot_manager::{CGImageExt, SCScreenshotManager};
 use serde::{Deserialize, Serialize};
 
 /// Display information returned to the frontend

examples/24_batched_apis_showcase.rs

@@ -32,7 +32,7 @@
 use screencapturekit::cm::CMSampleBuffer;
 use screencapturekit::cm::CMSampleBufferSCExt;
 use screencapturekit::prelude::*;
-use screencapturekit::screenshot_manager::SCScreenshotManager;
+use screencapturekit::screenshot_manager::{CGImageExt, SCScreenshotManager};
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};

src/async_api.rs

@@ -624,7 +624,8 @@ extern "C" fn screenshot_image_callback(
                 );
             }
         } else if !image_ptr.is_null() {
-            let image = crate::screenshot_manager::CGImage::from_ptr(image_ptr);
+            // SAFETY: the Swift bridge hands back a retained `CGImageRef` on success.
+            let image = unsafe { crate::screenshot_manager::cgimage_from_retained_ptr(image_ptr) };
             // SAFETY: `user_data` is the one-shot completion context from `AsyncCompletion::create()`; Swift invokes this callback exactly once, so the pointer is still valid.
             unsafe { AsyncCompletion::complete_ok(user_data, image) };
         } else {

src/cm/sample_buffer.rs

@@ -576,7 +576,7 @@ impl CMSampleBufferExt for CMSampleBuffer {
                 // Safety: the Swift bridge returns a retained CGImage on
                 // success; passing it straight to CGImage::from_raw takes
                 // ownership of that refcount.
-                Ok(apple_cf::cg::CGImage::from_raw(ptr as *mut std::ffi::c_void))
+                Ok(apple_cf::cg::CGImage::from_raw(ptr.cast_mut()))
             } else {
                 Err(status)
             }

src/cm/time.rs

@@ -3,42 +3,7 @@
 use std::ffi::c_void;
 use std::fmt;
 
-/// `CMTime` representation matching Core Media's `CMTime`
-///
-/// Represents a rational time value with a 64-bit numerator and 32-bit denominator.
-///
-/// # Examples
-///
-/// ```
-/// use screencapturekit::cm::CMTime;
-///
-/// // Create a time of 1 second (30/30)
-/// let time = CMTime::new(30, 30);
-/// assert_eq!(time.as_seconds(), Some(1.0));
-///
-/// // Create a time of 2.5 seconds at 1000 Hz timescale
-/// let time = CMTime::new(2500, 1000);
-/// assert_eq!(time.value, 2500);
-/// assert_eq!(time.timescale, 1000);
-/// assert_eq!(time.as_seconds(), Some(2.5));
-/// ```
-#[repr(C)]
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct CMTime {
-    pub value: i64,
-    pub timescale: i32,
-    pub flags: u32,
-    pub epoch: i64,
-}
-
-impl std::hash::Hash for CMTime {
-    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
-        self.value.hash(state);
-        self.timescale.hash(state);
-        self.flags.hash(state);
-        self.epoch.hash(state);
-    }
-}
+pub use apple_cf::cm::CMTime;
 
 /// Sample timing information
 ///
@@ -160,124 +125,6 @@ impl fmt::Display for CMSampleTimingInfo {
     }
 }
 
-impl CMTime {
-    pub const ZERO: Self = Self {
-        value: 0,
-        timescale: 0,
-        flags: 1,
-        epoch: 0,
-    };
-
-    pub const INVALID: Self = Self {
-        value: 0,
-        timescale: 0,
-        flags: 0,
-        epoch: 0,
-    };
-
-    pub const fn new(value: i64, timescale: i32) -> Self {
-        Self {
-            value,
-            timescale,
-            flags: 1,
-            epoch: 0,
-        }
-    }
-
-    pub const fn is_valid(&self) -> bool {
-        self.flags & 0x1 != 0
-    }
-
-    /// Check if this time represents zero
-    pub const fn is_zero(&self) -> bool {
-        self.value == 0 && self.is_valid()
-    }
-
-    /// Check if this time is indefinite
-    pub const fn is_indefinite(&self) -> bool {
-        self.flags & 0x2 != 0
-    }
-
-    /// Check if this time is positive infinity
-    pub const fn is_positive_infinity(&self) -> bool {
-        self.flags & 0x4 != 0
-    }
-
-    /// Check if this time is negative infinity
-    pub const fn is_negative_infinity(&self) -> bool {
-        self.flags & 0x8 != 0
-    }
-
-    /// Check if this time has been rounded
-    pub const fn has_been_rounded(&self) -> bool {
-        self.flags & 0x10 != 0
-    }
-
-    /// Compare two times for equality (value and timescale)
-    pub const fn equals(&self, other: &Self) -> bool {
-        if !self.is_valid() || !other.is_valid() {
-            return false;
-        }
-        self.value == other.value && self.timescale == other.timescale
-    }
-
-    /// Create a time representing positive infinity
-    pub const fn positive_infinity() -> Self {
-        Self {
-            value: 0,
-            timescale: 0,
-            flags: 0x5, // kCMTimeFlags_Valid | kCMTimeFlags_PositiveInfinity
-            epoch: 0,
-        }
-    }
-
-    /// Create a time representing negative infinity
-    pub const fn negative_infinity() -> Self {
-        Self {
-            value: 0,
-            timescale: 0,
-            flags: 0x9, // kCMTimeFlags_Valid | kCMTimeFlags_NegativeInfinity
-            epoch: 0,
-        }
-    }
-
-    /// Create an indefinite time
-    pub const fn indefinite() -> Self {
-        Self {
-            value: 0,
-            timescale: 0,
-            flags: 0x3, // kCMTimeFlags_Valid | kCMTimeFlags_Indefinite
-            epoch: 0,
-        }
-    }
-
-    pub fn as_seconds(&self) -> Option<f64> {
-        if self.is_valid() && self.timescale != 0 {
-            // Precision loss is acceptable for time conversion to seconds
-            #[allow(clippy::cast_precision_loss)]
-            Some(self.value as f64 / f64::from(self.timescale))
-        } else {
-            None
-        }
-    }
-}
-
-impl Default for CMTime {
-    fn default() -> Self {
-        Self::INVALID
-    }
-}
-
-impl fmt::Display for CMTime {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        if let Some(seconds) = self.as_seconds() {
-            write!(f, "{seconds:.3}s")
-        } else {
-            write!(f, "invalid")
-        }
-    }
-}
-
 /// `CMClock` wrapper for synchronization clock
 ///
 /// Represents a Core Media clock used for time synchronization.