apple-mps 0.2.1

Safe Rust bindings for Apple's MetalPerformanceShaders framework on macOS, backed by a Swift bridge
Documentation 
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

# mps-rs

Safe Rust bindings for Apple's
[`MetalPerformanceShaders`](https://developer.apple.com/documentation/metalperformanceshaders)
framework on macOS.

The GitHub repository is `mps-rs`; the published crates.io package is
`apple-mps` because the `mps-rs` package name is already taken.

## Install

```bash
cargo add apple-mps apple-metal
```

## Quick start

```rust,no_run
use apple_metal::MetalDevice;
use apple_mps::{feature_channel_format, Image, ImageDescriptor, ImageGaussianBlur};

let device = MetalDevice::system_default().expect("no Metal device");
let queue = device.new_command_queue().expect("queue");
let descriptor = ImageDescriptor::new(256, 256, 1, feature_channel_format::FLOAT32);
let src = Image::new(&device, descriptor).expect("source image");
let dst = Image::new(&device, descriptor).expect("destination image");
let blur = ImageGaussianBlur::new(&device, 2.0).expect("gaussian blur");
let command_buffer = queue.new_command_buffer().expect("command buffer");
blur.encode_image(&command_buffer, &src, &dst);
```

## v0.2.1 surface

- Core helpers:
  - `supports_mtl_device`, `preferred_device`, `hint_temporary_memory_high_water_mark`, `set_heap_cache_duration`
  - `Predicate` and `MpsCommandBuffer`
- Images:
  - `ImageDescriptor` + `Image` for lazily allocated MPS images or texture-backed images
  - Float32 image read/write helpers plus raw byte transfer with `MPSDataLayout`
  - Unary image filters:
    - `ImageGaussianBlur`
    - `ImageBox`
    - `ImageSobel`
    - `ImageMedian`
    - `ImageConvolution`
    - `ImageBilinearScale`
    - `ImageLanczosScale`
    - `ImageThresholdBinary`
    - `ImageStatisticsMinAndMax`
    - `ImageStatisticsMean`
    - `ImageReduceRowMin`, `ImageReduceRowMax`, `ImageReduceRowMean`, `ImageReduceRowSum`
  - `ImageHistogram`, `ImageAdd`, and `ImageScaleAndAdd`
- Matrix/vector:
  - `MatrixDescriptor`, `VectorDescriptor`, `MatrixMultiplicationDescriptor`, `Matrix`, `Vector`, and `MatrixMultiplication`
- `NDArray`:
  - `NDArrayDescriptor`, `NDArray`, `NDArrayIdentity`, and `NDArrayMatrixMultiplication`
- State:
  - `State`, `StateResourceList`, `StateTextureInfo`
  - `state_batch_increment_read_count`, `state_batch_resource_size`, `state_batch_synchronize`
- Ray tracing / denoising:
  - `PolygonAccelerationStructure`, `RayIntersector`, and `SVGF`
- Neural / optimizer / RNN:
  - `NNImageNode`, `NNGraph`
  - `CnnNeuronReluNode`, `CnnPoolingMaxNode`, `CnnSoftMaxNode`, `CnnUpsamplingNearestNode`
  - `CnnConvolutionDescriptor`, `CnnConvolution`, `CnnConvolutionWeightsAndBiasesState`
  - `NNOptimizerDescriptor`, `NNOptimizer`, `NNOptimizerStochasticGradientDescent`, `NNOptimizerRmsProp`, `NNOptimizerAdam`
  - `RnnDescriptor`, `RnnSingleGateDescriptor`, `GruDescriptor`, `LstmDescriptor`, `RnnImageInferenceLayer`, `RnnRecurrentImageState`
- Shared constants for `MPSKernelOptions`, `MPSImageEdgeMode`, `MPSImageFeatureChannelFormat`, `MPSDataType`, `MPSDataLayout`, plus convolution / optimizer / RNN / state enums

See [`COVERAGE.md`](COVERAGE.md) for the Wave-C audit and the implemented/partial matrix.

## Validation

```bash
cargo test
cargo run --example 01_blur_image
cargo run --example 02_matrix_multiply
cargo run --example 03_ndarray_identity
cargo run --example 04_ray_intersection
cargo run --example 05_nn_graph_relu
cargo run --example 06_ndarray_matrix_multiplication
cargo run --example 07_optimizer_and_state
cargo run --example 08_cnn_convolution
cargo run --example 09_rnn_image_inference
```