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

#![forbid(unsafe_code)]
#![deny(missing_docs)]

//! Safe Rust interfaces for Apple Metal.
//!
//! Raw Objective-C objects and unsafe operations are confined to the audited
//! `metal-rust-ffi` implementation crate. This public crate never exposes
//! object pointers or requires callers to uphold Objective-C runtime
//! invariants.
//!
//! The following visibility fixture must fail to compile: an application can
//! own a device, but cannot extract its implementation object or bypass the
//! safe boundary.
//!
//! ```compile_fail
//! let device = metal_rust::Device::system_default().unwrap();
//! let _implementation_object = device.inner;
//! ```
//!
//! GPU resource readback is also intentionally absent until synchronization
//! can be associated with the specific resource being read:
//!
//! ```compile_fail
//! let device = metal_rust::Device::system_default().unwrap();
//! let buffer = device
//!     .new_buffer(16, metal_rust::ResourceOptions::SHARED)
//!     .unwrap();
//! let _bytes = buffer.read(0, 16);
//! ```
//!
//! ```compile_fail
//! let device = metal_rust::Device::system_default().unwrap();
//! let descriptor = metal_rust::TextureDescriptor::new_2d(
//!     metal_rust::PixelFormat::RGBA8_UNORM,
//!     1,
//!     1,
//!     metal_rust::ResourceOptions::SHARED,
//!     metal_rust::TextureUsage::SHADER_READ,
//! )
//! .unwrap();
//! let texture = device.new_texture(&descriptor).unwrap();
//! let region = metal_rust::Region::new(
//!     metal_rust::Origin::new(0, 0, 0),
//!     metal_rust::Size::new(1, 1, 1),
//! );
//! let _bytes = texture.read_region(region, 4);
//! ```
//!
//! ```compile_fail
//! let device = metal_rust::Device::system_default().unwrap();
//! let heap = device.new_timestamp_counter_heap(1).unwrap();
//! let _timestamps = heap.resolve(0..1);
//! ```
//!
//! Submission consumes the recording-state command buffer, so it cannot be
//! committed twice:
//!
//! ```compile_fail
//! let device = metal_rust::Device::system_default().unwrap();
//! let queue = device.new_command_queue(None).unwrap();
//! let command_buffer = queue.command_buffer().unwrap();
//! let submitted = command_buffer.commit();
//! let _ = command_buffer.commit();
//! let _ = submitted;
//! ```
//!
//! An encoder's exclusive borrow also prevents submission while encoding is
//! active:
//!
//! ```compile_fail
//! let device = metal_rust::Device::system_default().unwrap();
//! let queue = device.new_command_queue(None).unwrap();
//! let mut command_buffer = queue.command_buffer().unwrap();
//! let encoder = command_buffer.blit_encoder().unwrap();
//! let _submitted = command_buffer.commit();
//! encoder.end_encoding();
//! ```

#[path = "Foundation/Foundation.rs"]
pub mod foundation;
#[path = "Private/GeneratedFacade.rs"]
mod generated_facade;
#[path = "Metal/Metal.rs"]
pub mod metal;
#[path = "Metal4/Metal4.rs"]
pub mod metal4;
#[path = "Metal4FX/Metal4FX.rs"]
pub mod metal4_fx;
#[path = "MetalFX/MetalFX.rs"]
pub mod metal_fx;
#[path = "QuartzCore/QuartzCore.rs"]
pub mod quartz_core;

pub use foundation::{Error, ErrorKind};
pub use metal::{
    BlitCommandEncoder, Buffer, BufferReadback, CaptureSession, ClearColor, CommandBuffer,
    CommandBufferStatus, CommandQueue, CompileOptions, CompletedCommandBuffer,
    ComputeCommandEncoder, ComputePassDescriptor, ComputePipelineState, Device, DeviceCapability,
    DeviceNumericProperty, Function, Library, MAX_TIMESTAMP_COUNTERS, Origin, PixelFormat,
    PrimitiveType, Region, RenderCommandEncoder, RenderPassDescriptor, RenderPassOptions,
    RenderPipelineDescriptor, RenderPipelineOptions, RenderPipelineState, ResourceOptions, Size,
    StorageMode, SubmittedCommandBuffer, Texture, TextureDescriptor, TextureReadback,
    TextureReadbackData, TextureType, TextureUsage, TimestampCounterHeap, Viewport,
};
pub use metal_fx::{
    Matrix4x4, MatrixValidationError, SpatialScaler, SpatialScalerColorProcessingMode,
    SpatialScalerDescriptor, TemporalScaler, TemporalScalerDescriptor,
};
pub use quartz_core::{Drawable, Layer};