objc2_metal/
lib.rs

1//! # Bindings to the `Metal` framework
2//!
3//! See [Apple's docs][apple-doc] and [the general docs on framework crates][framework-crates] for more information.
4//!
5//! [apple-doc]: https://developer.apple.com/documentation/metal/
6//! [framework-crates]: https://docs.rs/objc2/latest/objc2/topics/about_generated/index.html
7//!
8//! Metal has tools for validating that you're using it correctly, using these
9//! is highly recommended! See [Apple's documentation on it][apple-doc], or
10//! run `man MetalValidation` to get information on environment variables.
11//!
12//! [apple-doc]: https://developer.apple.com/documentation/xcode/validating-your-apps-metal-api-usage/.
13//!
14//! NOTE: To use [`MTLCreateSystemDefaultDevice`] you need to link to
15//! `CoreGraphics`, this can be done by using `objc2-core-graphics`, or by
16//! doing:
17//! ```rust
18//! #[link(name = "CoreGraphics", kind = "framework")]
19//! extern "C" {}
20//! ```
21//!
22#![cfg_attr(
23    not(feature = "MTLDevice"),
24    doc = "[`MTLCreateSystemDefaultDevice`]: #needs-MTLDevice-feature"
25)]
26//!
27//! # Safety considerations
28//!
29//! Metal allows running arbitrary code on the GPU. We treat memory safety
30//! issues on the GPU as just as unsafe as that which applies to the CPU. A
31//! few notes on this below.
32//!
33//! ## Shaders
34//!
35//! Shaders are (often) written in an unsafe C-like language.
36//!
37//! Loading them (via `MTLLibrary`, function stitching etc.) is perfectly
38//! safe, it is similar to dynamic linking. The restrictions that e.g.
39//! `libloading::Library::new` labours under do not apply, since there are no
40//! ctors in [the Metal Shading Language][msl-spec] (see section 4.2).
41//!
42//! Similarly, getting individual shaders (`MTLFunction`) is safe, we can
43//! model this as the same as calling `dlsym` (which just returns a pointer).
44//!
45//! _Calling_ functions though, is not safe. Even though they can have their
46//! parameter and return types checked at runtime, they may have additional
47//! restrictions not present in the signature (e.g. `__builtin_unreachable()`
48//! is possible in MSL, so is out-of-bounds accesses). If you view
49//! `MTLFunction` as essentially just an `unsafe fn()` pointer, this should be
50//! apparent.
51//!
52//! [msl-spec]: https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf
53//!
54//! ## Bounds checks
55//!
56//! It is yet unclear whether Metal APIs are bounds-checked on the CPU side or
57//! not, so APIs that take offsets / lengths are often unsafe.
58//!
59//! ## Synchronization
60//!
61//! `MTLResource` subclasses such as `MTLBuffer` and `MTLTexture` require
62//! synchronization between the CPU and the GPU, or between different threads
63//! on the GPU itself, so APIs taking these are often unsafe.
64//!
65//! ## Memory management and lifetimes
66//!
67//! Resources used in `MTL4CommandBuffer`s or command buffers with created
68//! with one of:
69//! - `MTLCommandBufferDescriptor::setRetainedReferences(false)`.
70//! - `MTLCommandQueue::commandBufferWithUnretainedReferences()`.
71//!
72//! Must be kept alive for as long as they're used.
73//!
74//! ## Type safety
75//!
76//! `MTLBuffer` is untyped (in a similar manner as a `[u8]` slice), you must
77//! ensure that any usage of it is done with valid types.
78#![recursion_limit = "256"]
79#![allow(non_snake_case)]
80#![no_std]
81#![cfg_attr(feature = "unstable-darwin-objc", feature(darwin_objc))]
82#![cfg_attr(docsrs, feature(doc_cfg))]
83// Update in Cargo.toml as well.
84#![doc(html_root_url = "https://docs.rs/objc2-metal/0.3.2")]
85
86#[cfg(feature = "alloc")]
87extern crate alloc;
88
89#[cfg(feature = "std")]
90extern crate std;
91
92#[cfg(feature = "MTLAccelerationStructureTypes")]
93mod acceleration_structure_types;
94#[cfg(feature = "MTLCaptureManager")]
95mod capture;
96#[cfg(feature = "MTLCounters")]
97mod counters;
98#[cfg(feature = "MTLDevice")]
99mod device;
100mod generated;
101#[cfg(feature = "unstable-private")]
102mod private;
103#[cfg(feature = "MTLRasterizationRate")]
104mod rasterization_rate;
105#[cfg(feature = "MTLResource")]
106mod resource;
107mod slice;
108#[cfg(feature = "MTLTexture")]
109mod texture;
110#[cfg(feature = "MTLTypes")]
111mod types;
112
113#[cfg(feature = "MTLAccelerationStructureTypes")]
114pub use self::acceleration_structure_types::MTLPackedFloat3;
115#[cfg(feature = "MTLCounters")]
116pub use self::counters::*;
117#[cfg(feature = "MTLDevice")]
118pub use self::device::*;
119#[allow(unused_imports, unreachable_pub)]
120pub use self::generated::*;
121#[cfg(feature = "unstable-private")]
122pub use self::private::MTLDevicePrivate;
123#[cfg(feature = "MTLResource")]
124pub use self::resource::*;
125#[cfg(all(feature = "MTLRenderCommandEncoder", feature = "MTLCommandEncoder"))]
126pub use self::slice::MTLRenderCommandEncoderSliceExt;
127#[cfg(feature = "MTLTexture")]
128pub use self::texture::*;
objc2_metal/lib.rs

objc2_metal/
lib.rs
