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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
//! A Metal renderer for Apple platforms, written against the Objective-C
//! runtime directly — no `metal-rs`, no `objc` crate, no build script.
//!
//! Behind the `metal` feature, and compiled only for Apple's Metal platforms:
//! macOS, iOS and iPadOS (Mac Catalyst included), tvOS and visionOS. The wgpu
//! [`Renderer`](crate::renderer::Renderer) remains the default and the complete
//! one; this is a second, self-contained path to the same scene graph for
//! callers who want to be on Metal with nothing between them and it.
//!
//! # Why you might want it
//!
//! - **No dependencies.** The whole backend is `objc_msgSend` plus
//! `#[link(name = "Metal", kind = "framework")]`. Nothing to audit but this
//! directory, and no C or C++ toolchain in the build.
//! - **Metal-native objects.** [`crate::metal::PassAttachments::from_raw`] takes textures an
//! app already owns, so a scene can be drawn into someone else's frame —
//! an AVFoundation pipeline, a SceneKit view, a Core Image chain.
//! - **A small surface to read.** One MSL file, one draw loop.
//!
//! # Getting a frame
//!
//! Offscreen, which needs no window and no main thread:
//!
//! ```no_run
//! # #[cfg(all(feature = "metal", target_os = "macos"))] {
//! use threers::metal::MetalHeadlessRenderer;
//! use threers::{Color, Material, Mesh, Object3D, PerspectiveCamera, Scene};
//! use threers::geometries::BoxGeometry;
//! use threers::materials::StandardMaterial;
//! use threers::lights::DirectionalLight;
//!
//! let mut hr = MetalHeadlessRenderer::builder().size(512, 512).msaa(4).build()?;
//! let mut scene = Scene::new();
//! scene.add(Object3D::mesh(Mesh::new(
//! BoxGeometry::new(1.0, 1.0, 1.0),
//! Material::Standard(StandardMaterial::new(Color::from_hex(0xff8844))),
//! )));
//! scene.add_light(DirectionalLight::new(Color::WHITE, 3.0));
//!
//! let mut camera = PerspectiveCamera::new(50.0, 1.0, 0.1, 100.0);
//! camera.position = threers::math::Vector3::new(2.0, 2.0, 3.0);
//! let rgba = hr.render_to_rgba(&mut scene, &camera)?;
//! std::fs::write("cube.png", threers::encode_png(512, 512, &rgba))?;
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! On screen, given an `NSView` from a window toolkit:
//!
//! ```no_run
//! # #[cfg(all(feature = "metal", target_os = "macos"))] {
//! # use threers::metal::{MetalDevice, MetalRenderer, MetalSurface};
//! # use threers::{PerspectiveCamera, Scene};
//! # fn demo(ns_view: *mut std::ffi::c_void, scene: &mut Scene, camera: &PerspectiveCamera)
//! # -> Result<(), threers::metal::MetalError> {
//! let device = MetalDevice::new()?;
//! let mut renderer = MetalRenderer::with_device(device.clone())?;
//! let surface = unsafe { MetalSurface::from_ns_view(&device, ns_view, 1280, 720, 4)? };
//!
//! if let Some(frame) = surface.next_frame() {
//! renderer.render(scene, camera, &frame.attachments())?; // presents the drawable
//! }
//! # Ok(()) }
//! # }
//! ```
//!
//! # Stereo, and visionOS
//!
//! [`crate::metal::MetalRenderer::render_views`] takes a view per eye. When they are
//! *layered* — one texture array, a slice each, same viewport — both are drawn
//! in **one pass**: the vertex stage reads its eye out of the instance id and
//! writes `render_target_array_index`, so the second eye costs pixels and not a
//! second traversal. Eyes with a texture or a viewport of their own get a pass
//! each instead, and the clear happens once per target.
//!
//! [`crate::metal::PassAttachments::with_reverse_z`] flips the depth convention to near-at-1,
//! which is the only one visionOS accepts.
//!
//! The `visionos` feature builds on both: see the `visionos` module for the
//! CompositorServices frame loop and ARKit world tracking.
//!
//! # What it draws
//!
//! Meshes, instanced meshes, line segments, points and sprites; `Basic`,
//! `Lambert`, `Phong`, `Standard`, `Physical`, `Normal`, `Depth`, `Toon`,
//! `Matcap`, `Line`, `Points` and `Sprite` materials; one base-colour map per
//! material; ambient, directional, point, spot and hemisphere lights; linear
//! and exponential fog; alpha blending, alpha test, per-vertex colour,
//! wireframe, and MSAA.
//!
//! Deliberately not here — reach for [`crate::renderer::Renderer`] instead:
//! shadow maps, post-processing, environment maps and IBL, skinning, morph
//! targets, and the normal / roughness / metalness / AO / emissive map slots.
//! Materials outside the list draw unlit in their base colour rather than
//! failing, so a scene authored for the wgpu path still renders.
//!
//! # Conventions
//!
//! Shared with the wgpu backend, so the two agree on a scene: clip-space depth
//! in `[0, 1]`, counter-clockwise front faces, top-left texture origin (with
//! [`Texture::flip_y`](crate::textures::Texture::flip_y) applied at upload),
//! light colours premultiplied by intensity, and three.js's punctual
//! attenuation.
//!
//! # Threads
//!
//! Render on any thread. [`crate::metal::MetalDevice`] is `Send + Sync` — share
//! one between threads, and its command queue with it — and the renderers,
//! targets, surfaces and post chains are `Send`: build one where it is
//! convenient and move it to the thread that draws. Each one is used by one
//! thread at a time, which is what `&mut self` already says.
//!
//! Every call that makes Objective-C objects drains its own autorelease pool,
//! dropping a value included, so a plain `std::thread` with no pool of its own
//! does not leak.
//!
//! Two calls want the main thread, because they touch a view:
//! [`crate::metal::MetalSurface::from_ns_view`] and, on UIKit platforms,
//! `MetalSurface::from_ui_view`. Both say so with an error
//! rather than leaving it to AppKit or UIKit. Everything after — `resize`,
//! `next_frame`, `render` — runs on the render thread, the way `MTKView`-free
//! engines drive a `CAMetalLayer`.
//!
//! For a fixed set of render threads that are reused — sized for the
//! performance cores, and capped low on iOS, tvOS and visionOS where cores and
//! thermal headroom are scarce — use [`crate::metal::MetalRenderPool`]: each
//! worker keeps its renderer and its caches from job to job, and the bounded
//! queue in front of them makes a producer wait or drop a frame rather than
//! run ahead of the GPU.
//!
//! A command buffer the system refuses — iOS rejects GPU work from an app in
//! the background — comes back from a readback as
//! [`crate::metal::MetalError::CommandBuffer`] rather than as stale pixels.
//!
//! # Layout
//!
//! | Module | Role |
//! |--------|------|
//! | [`crate::metal::objc`] | `objc_msgSend`, selectors, retain/release, autorelease pools |
//! | [`crate::metal::enums`] | Metal enumerants and by-value structs |
//! | [`crate::metal::resources`] | Textures, samplers, pipeline states |
//! | — | [`crate::metal::MetalDevice`], [`crate::metal::MetalRenderer`], [`crate::metal::MetalRenderTarget`], [`crate::metal::MetalSurface`] |
//! | — | [`crate::metal::MetalRenderPool`]: reusable render threads |
//! | — | [`crate::metal::MetalUi`]: a threers-ui UI over a frame (`ui`) |
// Built with `metal-fluid` alone as well as with `metal`: the device, the
// Objective-C glue, textures and fullscreen passes. Everything else here is
// the scene renderer, and needs `metal` (and so wgpu's half of the crate).
pub use ;
pub use ;
pub use compile_library;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use MetalRenderTarget;
pub use MetalUi;
// Moving a renderer to another thread.
//
// SAFETY: what these types hold is `MTLDevice`, `MTLCommandQueue`,
// `MTLLibrary`, `MTLFunction`, `MTLBuffer`, `MTLTexture`, `MTLSamplerState`,
// `MTLRenderPipelineState`, `MTLDepthStencilState`, a committed
// `MTLCommandBuffer` waiting to be read back, and (the surface) a
// `CAMetalLayer` — every one of which Apple documents as usable from any
// thread. Encoders and uncommitted command buffers, which are not, never
// outlive the call that made them. The raw `Id`s kept in a field
// (`MetalRenderer::capture_bound`) point into objects the same value owns.
//
// `Send` and not `Sync`: a renderer's caches are `&mut` state, and two threads
// encoding into one target would race on the GPU however Rust saw it. The
// device is the exception, and is `Sync` too — see `device.rs`.
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
unsafe
/// The hand-written part of the default library: meshes, surfaces and the
/// post passes not generated. [`shader_source`] is the whole library,
/// compiled by [`MetalDevice::new`].
pub const SHADER_SOURCE: &str = concat!;
/// The default library [`MetalDevice::new`] compiles: [`SHADER_SOURCE`] and
/// the post passes written once with [`passes!`](crate::passes) for both
/// backends — bloom's threshold and blur — and the shared functions in
/// place of their marker.
/// With `metal-fluid` alone there is no scene renderer, and the default
/// library is only what every Metal source starts with. The fluid's is
/// [`fluid_shader_source`].
/// The fluid's frame-rate read-out in MSL — the one part of the fluid's
/// shaders written by hand. The passes are generated from the `passes!`
/// source the wgpu module also runs; [`fluid_shader_source`] has the whole
/// thing.
pub const FLUID_SHADER_SOURCE: &str = include_str!;
/// The default library plus the fluid's, for a device that wants both.
///
/// ```no_run
/// # #[cfg(all(feature = "metal", feature = "fluid"))]
/// # fn demo() -> Result<(), threers::metal::MetalError> {
/// use threers::metal::{fluid_shader_source, MetalDevice};
/// let device = MetalDevice::with_shader_source(&fluid_shader_source())?;
/// # Ok(()) }
/// ```
///
/// Kept out of the default library because most Metal work is a scene and a
/// post chain, and a library is compiled once per device: a caller who will
/// never run a fluid should not pay for its twenty fragment functions.
pub use ;
pub use ;