mtl-rs 0.2.0

Rust bindings for Apple's Metal API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

#![allow(deprecated)]

use core::ptr::NonNull;

use block2::{Block, RcBlock};
use objc2::{rc::Retained, runtime::ProtocolObject};
use objc2_foundation::{NSArray, NSObjectProtocol, NSString};

use super::MTLDevice;

type RawDeviceNotificationName = NSString;

unsafe extern "C" {
    /// Posted when a Metal device is added to the system.
    #[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
    static MTLDeviceWasAddedNotification: &'static RawDeviceNotificationName;

    /// Posted when the user requests that an application stop using a device.
    #[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
    static MTLDeviceRemovalRequestedNotification: &'static RawDeviceNotificationName;

    /// Posted when a Metal device is removed from the system.
    #[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
    static MTLDeviceWasRemovedNotification: &'static RawDeviceNotificationName;
}

/// The name posted when a Metal device is added to the system.
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub fn device_was_added_notification() -> String {
    unsafe { MTLDeviceWasAddedNotification }.to_string()
}

/// The name posted when the user requests that an application stop using a device.
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub fn device_removal_requested_notification() -> String {
    unsafe { MTLDeviceRemovalRequestedNotification }.to_string()
}

/// The name posted when a Metal device is removed from the system.
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub fn device_was_removed_notification() -> String {
    unsafe { MTLDeviceWasRemovedNotification }.to_string()
}

type DeviceNotificationBlock = dyn Fn(NonNull<ProtocolObject<dyn MTLDevice>>, NonNull<RawDeviceNotificationName>);

/// A sendable handler used by the legacy Metal device-notification APIs.
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub struct MTLDeviceNotificationHandler(RcBlock<DeviceNotificationBlock>);

impl MTLDeviceNotificationHandler {
    /// Creates a handler whose captured state can safely be sent to and shared
    /// with Metal's callback thread.
    pub fn new<F>(handler: F) -> Self
    where
        F: Fn(&ProtocolObject<dyn MTLDevice>, &str) + Send + Sync + 'static,
    {
        Self(RcBlock::new(
            move |device: NonNull<ProtocolObject<dyn MTLDevice>>, name: NonNull<RawDeviceNotificationName>| {
                let name = unsafe { name.as_ref() }.to_string();
                handler(unsafe { device.as_ref() }, &name);
            },
        ))
    }
}

/// An opaque token that owns a legacy Metal device-change observer.
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub struct MTLDeviceObserver(Retained<ProtocolObject<dyn NSObjectProtocol>>);

/// Returns all devices and installs a legacy device-change observer.
///
/// The returned observer owns the +1 retain count documented by Metal. Pass
/// it to [`remove_device_observer`] to stop notifications.
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub fn copy_all_devices_with_observer(
    handler: &MTLDeviceNotificationHandler
) -> (Box<[Retained<ProtocolObject<dyn MTLDevice>>]>, Option<MTLDeviceObserver>) {
    unsafe extern "C" {
        fn MTLCopyAllDevicesWithObserver(
            observer: *mut *mut ProtocolObject<dyn NSObjectProtocol>,
            handler: &Block<DeviceNotificationBlock>,
        ) -> *mut NSArray<ProtocolObject<dyn MTLDevice>>;
    }

    let mut observer = core::ptr::null_mut();
    let devices = unsafe { MTLCopyAllDevicesWithObserver(&mut observer, &handler.0) };
    let devices = unsafe { Retained::from_raw(devices).expect("MTLCopyAllDevicesWithObserver returned a null array") };
    let observer = unsafe { Retained::from_raw(observer) }.map(MTLDeviceObserver);
    (devices.to_vec().into_boxed_slice(), observer)
}

/// Removes a legacy Metal device-change observer.
///
/// `observer` should be the object returned by
/// [`copy_all_devices_with_observer`].
#[deprecated(note = "Metal device notifications do not apply to Apple silicon")]
pub fn remove_device_observer(observer: MTLDeviceObserver) {
    unsafe extern "C" {
        fn MTLRemoveDeviceObserver(observer: &ProtocolObject<dyn NSObjectProtocol>);
    }

    unsafe { MTLRemoveDeviceObserver(&observer.0) };
}

#[cfg(test)]
mod tests {
    use std::sync::{Arc, atomic::AtomicBool};

    use super::MTLDeviceNotificationHandler;

    #[test]
    fn handler_accepts_sendable_shared_captures() {
        let state = Arc::new(AtomicBool::new(false));
        let state_for_handler = Arc::clone(&state);
        let _handler = MTLDeviceNotificationHandler::new(move |_, _| {
            state_for_handler.store(true, std::sync::atomic::Ordering::Relaxed);
        });
    }
}