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
//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
use objc2_foundation::*;
use crate::*;
/// Memory consistency options for synchronization commands.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4visibilityoptions?language=objc)
// NS_OPTIONS
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MTL4VisibilityOptions(pub NSUInteger);
bitflags::bitflags! {
impl MTL4VisibilityOptions: NSUInteger {
/// Don't flush caches. When you use this option on a barrier, it turns it into an execution barrier.
#[doc(alias = "MTL4VisibilityOptionNone")]
const None = 0;
/// Flushes caches to the GPU (device) memory coherence point.
#[doc(alias = "MTL4VisibilityOptionDevice")]
const Device = 1<<0;
/// Flushes caches to ensure that aliased virtual addresses are memory consistent.
///
/// On some systems this may be the GPU+CPU (system) memory coherence point
/// and on other systems it may be the GPU (device) memory coherence point.
#[doc(alias = "MTL4VisibilityOptionResourceAlias")]
const ResourceAlias = 1<<1;
}
}
unsafe impl Encode for MTL4VisibilityOptions {
const ENCODING: Encoding = NSUInteger::ENCODING;
}
unsafe impl RefEncode for MTL4VisibilityOptions {
const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}
extern_protocol!(
/// An encoder that writes GPU commands into a command buffer.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandencoder?language=objc)
pub unsafe trait MTL4CommandEncoder: NSObjectProtocol {
/// Provides an optional label to assign to the command encoder for debug purposes.
#[unsafe(method(label))]
#[unsafe(method_family = none)]
fn label(&self) -> Option<Retained<NSString>>;
/// Setter for [`label`][Self::label].
///
/// This is [copied][objc2_foundation::NSCopying::copy] when set.
#[unsafe(method(setLabel:))]
#[unsafe(method_family = none)]
fn setLabel(&self, label: Option<&NSString>);
#[cfg(feature = "MTL4CommandBuffer")]
/// Returns the command buffer that is currently encoding commands.
///
/// This property may return undefined results if you call it after calling ``endEncoding``.
#[unsafe(method(commandBuffer))]
#[unsafe(method_family = none)]
fn commandBuffer(&self) -> Option<Retained<ProtocolObject<dyn MTL4CommandBuffer>>>;
#[cfg(feature = "MTLCommandEncoder")]
/// Encodes a consumer barrier on work you commit to the same command queue.
///
/// Encode a barrier that guarantees that any subsequent work you encode in the current command encoder that corresponds
/// to the `beforeStages` stages doesn't proceed until Metal completes all work prior to the current command encoder
/// corresponding to the `afterQueueStages` stages, completes.
///
/// Metal can reorder the exact point where it applies the barrier, so encode the barrier as close to the command that
/// consumes the resource as possible. Don't use this method for synchronizing resource access within the same pass.
///
/// If you need to synchronize work within a pass that you encode with an instance of a subclass of ``MTLCommandEncoder``,
/// use memory barriers instead. For subclasses of ``MTL4CommandEncoder``, use encoder barriers.
///
/// You can specify `afterQueueStages` and `beforeStages` that contain ``MTLStages`` unrelated to the current command
/// encoder.
///
/// - Parameters:
/// - afterQueueStages: ``MTLStages`` mask that represents the stages of work to wait for.
/// This argument applies to work corresponding to these stages you
/// encode in prior command encoders, and not for the current encoder.
/// - beforeStages: ``MTLStages`` mask that represents the stages of work that wait.
/// This argument applies to work you encode in the current command encoder.
/// - visibilityOptions: ``MTL4VisibilityOptions`` of the barrier.
#[unsafe(method(barrierAfterQueueStages:beforeStages:visibilityOptions:))]
#[unsafe(method_family = none)]
fn barrierAfterQueueStages_beforeStages_visibilityOptions(
&self,
after_queue_stages: MTLStages,
before_stages: MTLStages,
visibility_options: MTL4VisibilityOptions,
);
#[cfg(feature = "MTLCommandEncoder")]
/// Encodes a producer barrier on work committed to the same command queue.
///
/// This method encodes a barrier that guarantees that any work you encode using *subsequent command encoders*,
/// corresponding to `beforeQueueStages`, don't begin until all commands you previously encode in the current
/// encoder (and prior encoders), corresponding to `afterStages`, complete.
///
/// When calling this method, you can pass any ``MTLStages`` to parameters `afterStages` and `beforeQueueStages`,
/// even stages that don't relate to the current or prior command encoders.
///
/// - Parameters:
/// - afterStages: ``MTLStages`` mask that represents the stages of work to wait for.
/// This argument applies to work corresponding to these stages you encode in
/// the current command encoder prior to this barrier command.
/// - beforeQueueStages: ``MTLStages`` mask that represents the stages of work that need to wait.
/// This argument applies to subsequent encoders and not to work in the current
/// command encoder.
/// - visibilityOptions: ``MTL4VisibilityOptions`` of the barrier, controlling cache flush behavior.
#[unsafe(method(barrierAfterStages:beforeQueueStages:visibilityOptions:))]
#[unsafe(method_family = none)]
fn barrierAfterStages_beforeQueueStages_visibilityOptions(
&self,
after_stages: MTLStages,
before_queue_stages: MTLStages,
visibility_options: MTL4VisibilityOptions,
);
#[cfg(feature = "MTLCommandEncoder")]
/// Encodes an intra-pass barrier.
///
/// Encode a barrier that guarantees that any subsequent work you encode in the *current command encoder*,
/// corresponding to `beforeEncoderStages`, doesn't begin until all prior commands in this command encoder,
/// corresponding to `afterEncoderStages`, completes.
///
/// When calling this method, it's your responsibility to ensure parameters `afterEncoderStages` and `beforeEncoderStages`
/// contain a combination of ``MTLStages`` for which this encoder can encode commands. For example, for a
/// ``MTL4ComputeCommandEncoder`` instance, you can provide any combination of ``MTLStages/MTLStageDispatch``,
/// ``MTLStages/MTLStageBlit`` and ``MTLStages/MTLStageAccelerationStructure``.
///
/// - Parameters:
/// - afterEncoderStages: ``MTLStages`` mask that represents the stages of work to wait for.
/// This argument only applies to subsequent work you encode in the current command encoder.
/// - beforeEncoderStages: ``MTLStages`` mask that represents the stages of work that wait.
/// This argument only applies to work you encode in the current command encoder prior to
/// this barrier.
/// - visibilityOptions: ``MTL4VisibilityOptions`` of the barrier, controlling cache flush behavior.
#[unsafe(method(barrierAfterEncoderStages:beforeEncoderStages:visibilityOptions:))]
#[unsafe(method_family = none)]
fn barrierAfterEncoderStages_beforeEncoderStages_visibilityOptions(
&self,
after_encoder_stages: MTLStages,
before_encoder_stages: MTLStages,
visibility_options: MTL4VisibilityOptions,
);
#[cfg(all(feature = "MTLCommandEncoder", feature = "MTLFence"))]
/// Encodes a command to update a GPU fence.
///
/// This method encodes a command that updates a ``MTLFence`` instance after all previously-encoded commands in the
/// current command encoder, corresponding to `afterEncoderStages`, complete.
///
/// Use parameter `afterEncoderStages` to pass in a combination of ``MTLStages`` for which this encoder can encode work.
/// For example, for a ``MTL4ComputeCommandEncoder`` you can provide any combination of ``MTLStages/MTLStageDispatch``,
/// ``MTLStages/MTLStageBlit`` and ``MTLStages/MTLStageAccelerationStructure``.
///
/// - Parameters:
/// - fence: ``MTLFence`` instance to update.
/// - afterEncoderStages: ``MTLStages`` value that represents the stages of work to wait for.
/// This argument only applies to work encoded in the current command encoder.
#[unsafe(method(updateFence:afterEncoderStages:))]
#[unsafe(method_family = none)]
fn updateFence_afterEncoderStages(
&self,
fence: &ProtocolObject<dyn MTLFence>,
after_encoder_stages: MTLStages,
);
#[cfg(all(feature = "MTLCommandEncoder", feature = "MTLFence"))]
/// Encodes a command to wait on a GPU fence.
///
/// Encode a command that guarantees that any subsequent work you encode via this current command encoder,
/// corresponding to `beforeEncoderStages`, doesn't begin until all prior updates to the fence is complete.
///
/// To successfully wait for a fence update, schedule update and wait operations on the same command queue.
///
/// Use parameter `beforeEncoderStages` to pass in a combination of ``MTLStages`` for which this encoder can encode
/// work. For example, for a ``MTL4ComputeCommandEncoder`` you can provide any combination of
/// ``MTLStages/MTLStageDispatch``, ``MTLStages/MTLStageBlit`` and ``MTLStages/MTLStageAccelerationStructure``.
///
/// - Parameters:
/// - fence: ``MTLFence`` instance to wait for.
/// - beforeEncoderStages:``MTLStages`` value that represents the stages of work that wait.
/// This argument only applies to work you encode in the current command encoder.
#[unsafe(method(waitForFence:beforeEncoderStages:))]
#[unsafe(method_family = none)]
fn waitForFence_beforeEncoderStages(
&self,
fence: &ProtocolObject<dyn MTLFence>,
before_encoder_stages: MTLStages,
);
/// Inserts a debug string into the frame data to aid debugging.
///
/// Calling this method doesn't change any behaviors, but can be useful for debugging purposes.
///
/// - Parameter string: The debug string to insert as a signpost.
#[unsafe(method(insertDebugSignpost:))]
#[unsafe(method_family = none)]
fn insertDebugSignpost(&self, string: &NSString);
/// Pushes a string onto this encoder's stack of debug groups.
///
/// - Parameter string: The debug string to push.
#[unsafe(method(pushDebugGroup:))]
#[unsafe(method_family = none)]
fn pushDebugGroup(&self, string: &NSString);
/// Pops the latest debug group string from this encoder's stack of debug groups.
#[unsafe(method(popDebugGroup))]
#[unsafe(method_family = none)]
fn popDebugGroup(&self);
/// Declares that all command generation from this encoder is complete.
#[unsafe(method(endEncoding))]
#[unsafe(method_family = none)]
fn endEncoding(&self);
}
);