metal-rust 1.0.0

Safe Rust interfaces for Apple Metal
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
121

# Metal-Rust

Safe Rust interfaces for Apple Metal. The API follows the same framework and
protocol surface as Apple's metal-cpp, while making Objective-C ownership and
message-send invariants private implementation details.

## Safety boundary

- The public `metal-rust` crate uses `#![forbid(unsafe_code)]`.
- Raw Objective-C interop is confined to the separately audited
  `metal-rust-ffi` workspace crate. That implementation crate is published only
  so package registries can resolve `metal-rust`; applications should depend on
  `metal-rust`, and both crates expose safe Rust APIs only.
- Public APIs return owned Rust values and typed RAII objects. They never expose
  Objective-C pointers, selectors, `NSError **`, retain/release, or unchecked
  ranges.
- APIs whose safety depends on GPU synchronization remain unavailable until
  resource use and command completion can be tied together by the type system.

The safe facade covers the core Metal submission/resource path, Metal 4
timestamp CounterHeap ownership, device-wide capture, MetalFX spatial and
temporal scaler descriptors, and CAMetalLayer drawable ownership. The full
metal-cpp reference inventory is tracked in
[`api/metal-cpp-inventory.json`](api/metal-cpp-inventory.json), with one
explicit implemented or unimplemented status per declaration in
[`api/coverage.json`](api/coverage.json). Only audited facade mappings count as
coverage; a transitive generated binding does not.

The audited generated layer currently supplies owned opaque wrappers, safe
scalar and struct representations, non-callback aliases, runtime-gated default
constructors, and checked property accessors. Generated `try_*` getters return
`None` when a selector is unavailable; enum setters reject undeclared values,
floating-point setters reject non-finite values, and object/string setters keep
all Objective-C ownership inside `metal-rust-ffi`. Methods involving callbacks,
raw buffers, synchronization, or API-specific numeric constraints remain
explicitly `unimplemented` until their contracts are represented safely.

## Source layout

Framework directories and API filenames intentionally track metal-cpp:

```text
src/
  Foundation/
    Foundation.rs
    NSError.rs
  Metal/
    Metal.rs
    MTLBuffer.rs
    MTLBlitCommandEncoder.rs
    MTLCommandBuffer.rs
    MTLCommandEncoder.rs
    MTLCommandQueue.rs
    MTLRenderPass.rs
    MTLShader.rs
    MTLTexture.rs
    MTLTypes.rs
    MTLDevice.rs
    MTLCaptureManager.rs
    MTL4Counters.rs
  MetalFX/
    MetalFX.rs
    MTLFXSpatialScaler.rs
    MTLFXTemporalScaler.rs
  QuartzCore/
    CAMetalLayer.rs
    QuartzCore.rs
```

The implementation-only `metal-rust-ffi/src/` tree uses the same
Foundation/Metal mapping,
so an API has a predictable public facade and Objective-C implementation file.
Rust module names remain snake_case, while source filenames retain Apple's
framework spelling for direct comparison with metal-cpp and SDK declarations.

## Safe workflow

The normal workflow is entirely safe Rust: create a `Device` and
`CommandQueue`, allocate shared `Buffer`/`Texture` resources, compile a
`Library` and `Function`, build a pipeline, encode render/compute/blit work,
then commit and wait on the `CommandBuffer`. GPU-written resource readback is
intentionally not exposed yet: completion of an unrelated command buffer is
not proof that a particular resource is idle. `Layer::next_drawable` and
`CommandBuffer::present_drawable` cover presentation when Core Animation can
provide a drawable. `CaptureSession`, MetalFX descriptors, and the Metal 4
counter heap return owned `Error` values when the installed runtime does not
support the requested capability. No resource readback API exposes mapped GPU
memory before a resource-specific synchronization model is implemented.

## Reference

The API organization and naming are informed by Apple's metal-cpp distribution.
metal-cpp and this project are licensed under Apache License 2.0. Objective-C
binding generation is provided internally by the Apache/MIT/Zlib-licensed
`objc2` project; its raw bindings are not re-exported.

## Development

Use Conventional Commit subjects in the form `type(scope): summary`. The
reviewed types and scopes live in
[`scripts/conventional-commit-keywords.sh`](scripts/conventional-commit-keywords.sh),
and the repository hook validates local commit subjects. Install it with:

```sh
scripts/install-git-hooks.sh
```

Before submitting a change, run:

```sh
cargo fmt --all -- --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
scripts/check-commit-message.sh --self-test
python3 scripts/check-api-coverage.py
python3 scripts/check-safety.py
```

See [RELEASING.md](RELEASING.md) for the crates.io publication order and
release checks. General pull-request CI is intentionally deferred; releases
use a manual workflow on the organization's macOS runner.