objc2_metal/generated/MTL4ComputeCommandEncoder.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7
8use crate::*;
9
10extern_protocol!(
11 /// Encodes a compute pass and other memory operations into a command buffer.
12 ///
13 /// Use instances of this abstraction to encode a compute pass into ``MTL4CommandBuffer`` instances, as well as commands
14 /// that copy and modify the underlying memory of various Metal resources, and commands that build or refit acceleration
15 /// structures.
16 ///
17 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4computecommandencoder?language=objc)
18 #[cfg(feature = "MTL4CommandEncoder")]
19 pub unsafe trait MTL4ComputeCommandEncoder: MTL4CommandEncoder {
20 #[cfg(feature = "MTLCommandEncoder")]
21 /// Queries a bitmask representing the shader stages on which commands currently present in this command encoder
22 /// operate.
23 ///
24 /// Metal dynamically updates this property based on the commands you encode into the command encoder, for example,
25 /// it sets the bit ``MTLStages/MTLStageDispatch`` if this encoder contains any commands that dispatch a compute kernel.
26 ///
27 /// Similarly, it sets the bit ``MTLStages/MTLStageBlit`` if this encoder contains any commands to copy or modify buffers,
28 /// textures, or indirect command buffers.
29 ///
30 /// Finally, Metal sets the bit ``MTLStages/MTLStageAccelerationStructure`` if this encoder contains any commands that
31 /// build, copy, or refit acceleration structures.
32 ///
33 /// - Returns: a bitmask representing shader stages that commands currently present in this command encoder operate on.
34 #[unsafe(method(stages))]
35 #[unsafe(method_family = none)]
36 fn stages(&self) -> MTLStages;
37
38 #[cfg(all(feature = "MTLAllocation", feature = "MTLComputePipeline"))]
39 /// Configures this encoder with a compute pipeline state that applies to your subsequent dispatch commands.
40 ///
41 /// - Parameter state: a non-`nil` ``MTLComputePipelineState``.
42 #[unsafe(method(setComputePipelineState:))]
43 #[unsafe(method_family = none)]
44 fn setComputePipelineState(&self, state: &ProtocolObject<dyn MTLComputePipelineState>);
45
46 /// Configures the size of a threadgroup memory buffer for a threadgroup argument in the compute shader function.
47 ///
48 /// - Parameters:
49 /// - length: The size of the threadgroup memory, in bytes. Use a multiple of `16` bytes.
50 /// - index: An integer that corresponds to the index of the argument you annotate with attribute `[[threadgroup(index)]]`
51 /// in the shader function.
52 ///
53 /// # Safety
54 ///
55 /// `index` might not be bounds-checked.
56 #[unsafe(method(setThreadgroupMemoryLength:atIndex:))]
57 #[unsafe(method_family = none)]
58 unsafe fn setThreadgroupMemoryLength_atIndex(&self, length: NSUInteger, index: NSUInteger);
59
60 /// Specifies the size, in pixels, of imageblock data in tile memory.
61 ///
62 /// - Parameters:
63 /// - width: The width of the imageblock, in pixels.
64 /// - height: The height of the imageblock, in pixels.
65 #[unsafe(method(setImageblockWidth:height:))]
66 #[unsafe(method_family = none)]
67 fn setImageblockWidth_height(&self, width: NSUInteger, height: NSUInteger);
68
69 #[cfg(feature = "MTLTypes")]
70 /// Encodes a compute dispatch command using an arbitrarily-sized grid.
71 ///
72 /// - Parameters:
73 /// - threadsPerGrid: An ``MTLSize`` instance that represents the number of threads in the grid,
74 /// in each dimension.
75 /// - threadsPerThreadgroup: An ``MTLSize`` instance that represents the number of threads in one
76 /// threadgroup, in each dimension.
77 #[unsafe(method(dispatchThreads:threadsPerThreadgroup:))]
78 #[unsafe(method_family = none)]
79 fn dispatchThreads_threadsPerThreadgroup(
80 &self,
81 threads_per_grid: MTLSize,
82 threads_per_threadgroup: MTLSize,
83 );
84
85 #[cfg(feature = "MTLTypes")]
86 /// Encodes a compute dispatch command with a grid that aligns to threadgroup boundaries.
87 ///
88 /// - Parameters:
89 /// - threadgroupsPerGrid: An ``MTLSize`` instance that represents the number of threadgroups in the grid,
90 /// in each dimension.
91 /// - threadsPerThreadgroup: An ``MTLSize`` instance that represents the number of threads in one
92 /// threadgroup, in each dimension.
93 #[unsafe(method(dispatchThreadgroups:threadsPerThreadgroup:))]
94 #[unsafe(method_family = none)]
95 fn dispatchThreadgroups_threadsPerThreadgroup(
96 &self,
97 threadgroups_per_grid: MTLSize,
98 threads_per_threadgroup: MTLSize,
99 );
100
101 #[cfg(all(feature = "MTLGPUAddress", feature = "MTLTypes"))]
102 /// Encodes a compute dispatch command with a grid that aligns to threadgroup boundaries, using an indirect buffer
103 /// for arguments.
104 ///
105 /// This method allows you to supply the threadgroups-per-grid counts indirectly via an ``MTLBuffer`` index. This
106 /// enables you to calculate this value in the GPU timeline from a shader function, enabling GPU-driven workflows.
107 ///
108 /// Metal assumes that the buffer contents correspond to the layout of struct ``MTLDispatchThreadgroupsIndirectArguments``.
109 /// You are responsible for ensuring this address aligns to 4-bytes.
110 ///
111 /// Use an instance of ``MTLResidencySet`` to mark residency of the indirect buffer that the `indirectBuffer`
112 /// parameter references.
113 ///
114 /// - Parameters:
115 /// - indirectBuffer: GPUAddress of a ``MTLBuffer`` instance providing compute parameters.
116 /// Lay out the data in this buffer as described in the
117 /// ``MTLDispatchThreadgroupsIndirectArguments`` structure. This address
118 /// requires 4-byte alignment.
119 /// - threadsPerThreadgroup: A ``MTLSize`` instance that represents the number of threads in one
120 /// threadgroup, in each dimension.
121 #[unsafe(method(dispatchThreadgroupsWithIndirectBuffer:threadsPerThreadgroup:))]
122 #[unsafe(method_family = none)]
123 unsafe fn dispatchThreadgroupsWithIndirectBuffer_threadsPerThreadgroup(
124 &self,
125 indirect_buffer: MTLGPUAddress,
126 threads_per_threadgroup: MTLSize,
127 );
128
129 #[cfg(feature = "MTLGPUAddress")]
130 /// Encodes a compute dispatch command with an arbitrarily sized grid, using an indirect buffer for arguments.
131 ///
132 /// - Parameters:
133 /// - indirectBuffer: GPUAddress of a ``MTLBuffer`` instance providing arguments. Lay out the data
134 /// in this buffer as described in the ``MTLDispatchThreadsIndirectArguments``
135 /// structure. This address requires 4-byte alignment.
136 #[unsafe(method(dispatchThreadsWithIndirectBuffer:))]
137 #[unsafe(method_family = none)]
138 fn dispatchThreadsWithIndirectBuffer(&self, indirect_buffer: MTLGPUAddress);
139
140 #[cfg(all(
141 feature = "MTLAllocation",
142 feature = "MTLIndirectCommandBuffer",
143 feature = "MTLResource"
144 ))]
145 /// Encodes a command to execute a series of commands from an indirect command buffer.
146 ///
147 /// - Parameters:
148 /// - indirectCommandBuffer: ``MTLIndirectCommandBuffer`` instance containing the commands to execute.
149 /// - executionRange: The range of commands to execute.
150 ///
151 /// # Safety
152 ///
153 /// - `indirect_command_buffer` may need to be synchronized.
154 /// - `indirect_command_buffer` may be unretained, you must ensure it is kept alive while in use.
155 /// - `executionRange` might not be bounds-checked.
156 #[unsafe(method(executeCommandsInBuffer:withRange:))]
157 #[unsafe(method_family = none)]
158 unsafe fn executeCommandsInBuffer_withRange(
159 &self,
160 indirect_command_buffer: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
161 execution_range: NSRange,
162 );
163
164 #[cfg(all(
165 feature = "MTLAllocation",
166 feature = "MTLGPUAddress",
167 feature = "MTLIndirectCommandBuffer",
168 feature = "MTLResource"
169 ))]
170 /// Encodes an instruction to execute commands from an indirect command buffer, using an indirect buffer for
171 /// arguments.
172 ///
173 /// Use an instance of ``MTLResidencySet`` to mark residency of the indirect buffer that the `indirectRangeBuffer`
174 /// parameter references.
175 ///
176 /// - Parameters:
177 /// - indirectCommandbuffer: ``MTLIndirectCommandBuffer`` instance containing the commands to execute.
178 /// - indirectRangeBuffer: GPUAddress of a ``MTLBuffer`` containing the execution range. Lay out the data
179 /// in this buffer as described in the ``MTLIndirectCommandBufferExecutionRange``
180 /// structure. This address requires 4-byte alignment.
181 ///
182 /// # Safety
183 ///
184 /// - `indirect_commandbuffer` may need to be synchronized.
185 /// - `indirect_commandbuffer` may be unretained, you must ensure it is kept alive while in use.
186 /// - `indirectRangeBuffer` might not be bounds-checked.
187 #[unsafe(method(executeCommandsInBuffer:indirectBuffer:))]
188 #[unsafe(method_family = none)]
189 unsafe fn executeCommandsInBuffer_indirectBuffer(
190 &self,
191 indirect_commandbuffer: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
192 indirect_range_buffer: MTLGPUAddress,
193 );
194
195 #[cfg(all(
196 feature = "MTLAllocation",
197 feature = "MTLResource",
198 feature = "MTLTexture"
199 ))]
200 /// Encodes a command that copies data from a texture to another.
201 ///
202 /// - Parameters:
203 /// - sourceTexture: An ``MTLTexture`` instance the command copies data from.
204 /// - destinationTexture: Another ``MTLTexture`` instance the command copies the data into that has the same
205 /// ``MTLTexture/pixelFormat`` and ``MTLTexture/sampleCount`` as `sourceTexture`.
206 ///
207 /// # Safety
208 ///
209 /// - `source_texture` may need to be synchronized.
210 /// - `source_texture` may be unretained, you must ensure it is kept alive while in use.
211 /// - `destination_texture` may need to be synchronized.
212 /// - `destination_texture` may be unretained, you must ensure it is kept alive while in use.
213 #[unsafe(method(copyFromTexture:toTexture:))]
214 #[unsafe(method_family = none)]
215 unsafe fn copyFromTexture_toTexture(
216 &self,
217 source_texture: &ProtocolObject<dyn MTLTexture>,
218 destination_texture: &ProtocolObject<dyn MTLTexture>,
219 );
220
221 #[cfg(all(
222 feature = "MTLAllocation",
223 feature = "MTLResource",
224 feature = "MTLTexture"
225 ))]
226 /// Encodes a command that copies slices of a texture to slices of another texture.
227 ///
228 /// - Parameters:
229 /// - sourceTexture: A ``MTLTexture`` texture that the command copies data from. To read the source
230 /// texture contents, you need to set its ``MTLTexture/framebufferOnly`` property
231 /// to
232 /// <doc
233 /// ://com.apple.documentation/documentation/swift/false> prior to drawing into it.
234 /// - sourceSlice: A slice within `sourceTexture` the command uses as a starting point to copy
235 /// data from. Set this to `0` if `sourceTexture` isn’t a texture array or a
236 /// cube texture.
237 /// - sourceLevel: A mipmap level within `sourceTexture`.
238 /// - destinationTexture: Another ``MTLTexture`` the command copies the data to that has the same
239 /// ``MTLTexture/pixelFormat`` and ``MTLTexture/sampleCount`` as `sourceTexture`.
240 /// To write the contents into this texture, you need to set its ``MTLTexture/framebufferOnly``
241 /// property to
242 /// <doc
243 /// ://com.apple.documentation/documentation/swift/false>.
244 /// - destinationSlice: A slice within `destinationTexture` the command uses as its starting point
245 /// for copying data to. Set this to `0` if `destinationTexture` isn’t a texture
246 /// array or a cube texture.
247 /// - destinationLevel: A mipmap level within `destinationTexture`. The mipmap level you reference needs to
248 /// have the same size as the `sourceTexture` slice's mipmap at `sourceLevel`.
249 /// - sliceCount: The number of slices the command copies so that it satisfies the conditions
250 /// that the sum of `sourceSlice` and `sliceCount` doesn’t exceed the number of
251 /// slices in `sourceTexture` and the sum of `destinationSlice` and `sliceCount`
252 /// doesn’t exceed the number of slices in `destinationTexture`.
253 /// - levelCount: The number of mipmap levels the command copies so that it satisfies the
254 /// conditions that the sum of `sourceLevel` and `levelCount` doesn’t exceed the
255 /// number of mipmap levels in `sourceTexture` and the sum of `destinationLevel`
256 /// and `levelCount` doesn’t exceed the number of mipmap levels in `destinationTexture`.
257 ///
258 /// # Safety
259 ///
260 /// - `source_texture` may need to be synchronized.
261 /// - `source_texture` may be unretained, you must ensure it is kept alive while in use.
262 /// - `destination_texture` may need to be synchronized.
263 /// - `destination_texture` may be unretained, you must ensure it is kept alive while in use.
264 /// - `sliceCount` might not be bounds-checked.
265 /// - `levelCount` might not be bounds-checked.
266 #[unsafe(method(copyFromTexture:sourceSlice:sourceLevel:toTexture:destinationSlice:destinationLevel:sliceCount:levelCount:))]
267 #[unsafe(method_family = none)]
268 unsafe fn copyFromTexture_sourceSlice_sourceLevel_toTexture_destinationSlice_destinationLevel_sliceCount_levelCount(
269 &self,
270 source_texture: &ProtocolObject<dyn MTLTexture>,
271 source_slice: NSUInteger,
272 source_level: NSUInteger,
273 destination_texture: &ProtocolObject<dyn MTLTexture>,
274 destination_slice: NSUInteger,
275 destination_level: NSUInteger,
276 slice_count: NSUInteger,
277 level_count: NSUInteger,
278 );
279
280 #[cfg(all(
281 feature = "MTLAllocation",
282 feature = "MTLResource",
283 feature = "MTLTexture",
284 feature = "MTLTypes"
285 ))]
286 /// Encodes a command that copies image data from a slice of a texture into a slice of another texture.
287 ///
288 /// - Parameters:
289 /// - sourceTexture: An ``MTLTexture`` texture that the command copies data from. To read the source
290 /// texture contents, you need to set its ``MTLTexture/framebufferOnly`` property
291 /// to
292 /// <doc
293 /// ://com.apple.documentation/documentation/swift/false> prior to drawing into it.
294 /// - sourceSlice: A slice within `sourceTexture` the command uses as a starting point to copy
295 /// data from. Set this to `0` if `sourceTexture` isn’t a texture array or a
296 /// cube texture.
297 /// - sourceLevel: A mipmap level within `sourceTexture`.
298 /// - sourceOrigin: An ``MTLOrigin`` instance that represents a location within `sourceTexture`
299 /// that the command begins copying data from. Assign `0` to each dimension
300 /// that’s not relevant to `sourceTexture`.
301 /// - sourceSize: An ``MTLSize`` instance that represents the size of the region, in pixels,
302 /// that the command copies from `sourceTexture`, starting at `sourceOrigin`.
303 /// Assign `1` to each dimension that’s not relevant to `sourceTexture`. If
304 /// sourceTexture uses a compressed pixel format, set `sourceSize` to a multiple
305 /// of the pixel format’s block size. If the block extends outside the bounds of
306 /// the texture, clamp `sourceSize` to the edge of the texture.
307 /// - destinationTexture: Another ``MTLTexture`` the command copies the data to that has the same
308 /// ``MTLTexture/pixelFormat`` and ``MTLTexture/sampleCount`` as `sourceTexture`.
309 /// To write the contents into this texture, you need to set its ``MTLTexture/framebufferOnly``
310 /// property to
311 /// <doc
312 /// ://com.apple.documentation/documentation/swift/false>.
313 /// - destinationSlice: A slice within `destinationTexture` the command uses as its starting point
314 /// for copying data to. Set this to `0` if `destinationTexture` isn’t a texture
315 /// array or a cube texture.
316 /// - destinationLevel: A mipmap level within `destinationTexture`. The mipmap level you reference needs to
317 /// have the same size as the `sourceTexture` slice's mipmap at `sourceLevel`.
318 /// - destinationOrigin: An ``MTLOrigin`` instance that represents a location within `destinationTexture`
319 /// that the command begins copying data to. Assign `0` to each dimension that’s
320 /// not relevant to `destinationTexture`.
321 ///
322 /// # Safety
323 ///
324 /// - `source_texture` may need to be synchronized.
325 /// - `source_texture` may be unretained, you must ensure it is kept alive while in use.
326 /// - `sourceSize` might not be bounds-checked.
327 /// - `destination_texture` may need to be synchronized.
328 /// - `destination_texture` may be unretained, you must ensure it is kept alive while in use.
329 #[unsafe(method(copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:))]
330 #[unsafe(method_family = none)]
331 unsafe fn copyFromTexture_sourceSlice_sourceLevel_sourceOrigin_sourceSize_toTexture_destinationSlice_destinationLevel_destinationOrigin(
332 &self,
333 source_texture: &ProtocolObject<dyn MTLTexture>,
334 source_slice: NSUInteger,
335 source_level: NSUInteger,
336 source_origin: MTLOrigin,
337 source_size: MTLSize,
338 destination_texture: &ProtocolObject<dyn MTLTexture>,
339 destination_slice: NSUInteger,
340 destination_level: NSUInteger,
341 destination_origin: MTLOrigin,
342 );
343
344 #[cfg(all(
345 feature = "MTLAllocation",
346 feature = "MTLBuffer",
347 feature = "MTLResource",
348 feature = "MTLTexture",
349 feature = "MTLTypes"
350 ))]
351 /// Encodes a command that copies image data from a slice of an ``MTLTexture`` instance to an ``MTLBuffer`` instance.
352 ///
353 /// - Parameters:
354 /// - sourceTexture: An ``MTLTexture`` texture that the command copies data from. To read the source
355 /// texture contents, you need to set its ``MTLTexture/framebufferOnly`` property
356 /// to
357 /// <doc
358 /// ://com.apple.documentation/documentation/swift/false> prior to drawing into it.
359 /// - sourceSlice: A slice within `sourceTexture` the command uses as a starting point to copy
360 /// data from. Set this to `0` if `sourceTexture` isn’t a texture array or a
361 /// cube texture.
362 /// - sourceLevel: A mipmap level within `sourceTexture`.
363 /// - sourceOrigin: An ``MTLOrigin`` instance that represents a location within `sourceTexture`
364 /// that the command begins copying data from. Assign `0` to each dimension
365 /// that’s not relevant to `sourceTexture`.
366 /// - sourceSize: An ``MTLSize`` instance that represents the size of the region, in pixels,
367 /// that the command copies from `sourceTexture`, starting at `sourceOrigin`.
368 /// Assign `1` to each dimension that’s not relevant to `sourceTexture`.
369 /// If `sourceTexture` uses a compressed pixel format, set `sourceSize` to a
370 /// multiple of the `sourceTexture's` ``MTLTexture/pixelFormat`` block size.
371 /// If the block extends outside the bounds of the texture, clamp `sourceSize`
372 /// to the edge of the texture.
373 /// - destinationBuffer: An ``MTLBuffer`` instance the command copies data to.
374 /// - destinationOffset: A byte offset within `destinationBuffer` the command copies to. The value
375 /// you provide as this argument needs to be a multiple of `sourceTexture's` pixel size,
376 /// in bytes.
377 /// - destinationBytesPerRow: The number of bytes between adjacent rows of pixels in `destinationBuffer`.
378 /// This value must be a multiple of `sourceTexture's` pixel size, in bytes,
379 /// and less than or equal to the product of `sourceTexture's` pixel size,
380 /// in bytes, and the largest pixel width `sourceTexture’s` type allows. If
381 /// `sourceTexture` uses a compressed pixel format, set `destinationBytesPerRow`
382 /// to the number of bytes between the starts of two row blocks.
383 /// - destinationBytesPerImage: The number of bytes between each 2D image of a 3D texture. This value must
384 /// be a multiple of `sourceTexture's` pixel size, in bytes. Set this value to
385 /// `0` if `sourceSize's` ``MTLSize/depth`` value is `1`.
386 ///
387 /// # Safety
388 ///
389 /// - `source_texture` may need to be synchronized.
390 /// - `source_texture` may be unretained, you must ensure it is kept alive while in use.
391 /// - `sourceSize` might not be bounds-checked.
392 /// - `destination_buffer` may need to be synchronized.
393 /// - `destination_buffer` may be unretained, you must ensure it is kept alive while in use.
394 /// - `destination_buffer` contents should be of the correct type.
395 /// - `destinationOffset` might not be bounds-checked.
396 #[unsafe(method(copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:))]
397 #[unsafe(method_family = none)]
398 unsafe fn copyFromTexture_sourceSlice_sourceLevel_sourceOrigin_sourceSize_toBuffer_destinationOffset_destinationBytesPerRow_destinationBytesPerImage(
399 &self,
400 source_texture: &ProtocolObject<dyn MTLTexture>,
401 source_slice: NSUInteger,
402 source_level: NSUInteger,
403 source_origin: MTLOrigin,
404 source_size: MTLSize,
405 destination_buffer: &ProtocolObject<dyn MTLBuffer>,
406 destination_offset: NSUInteger,
407 destination_bytes_per_row: NSUInteger,
408 destination_bytes_per_image: NSUInteger,
409 );
410
411 #[cfg(all(
412 feature = "MTLAllocation",
413 feature = "MTLBlitCommandEncoder",
414 feature = "MTLBuffer",
415 feature = "MTLResource",
416 feature = "MTLTexture",
417 feature = "MTLTypes"
418 ))]
419 /// Encodes a command that copies image data from a slice of a texture instance to a buffer, with
420 /// options for special texture formats.
421 ///
422 /// - Parameters:
423 /// - sourceTexture: An ``MTLTexture`` texture that the command copies data from. To read the source
424 /// texture contents, you need to set its ``MTLTexture/framebufferOnly`` property
425 /// to
426 /// <doc
427 /// ://com.apple.documentation/documentation/swift/false> prior to drawing into it.
428 /// - sourceSlice: A slice within `sourceTexture` the command uses as a starting point to copy
429 /// data from. Set this to `0` if `sourceTexture` isn’t a texture array or a
430 /// cube texture.
431 /// - sourceLevel: A mipmap level within `sourceTexture`.
432 /// - sourceOrigin: An ``MTLOrigin`` instance that represents a location within `sourceTexture`
433 /// that the command begins copying data from. Assign `0` to each dimension
434 /// that’s not relevant to `sourceTexture`.
435 /// - sourceSize: An ``MTLSize`` instance that represents the size of the region, in pixels,
436 /// that the command copies from `sourceTexture`, starting at `sourceOrigin`.
437 /// Assign `1` to each dimension that’s not relevant to `sourceTexture`.
438 /// If `sourceTexture` uses a compressed pixel format, set `sourceSize` to a
439 /// multiple of the `sourceTexture's` ``MTLTexture/pixelFormat`` block size.
440 /// If the block extends outside the bounds of the texture, clamp `sourceSize`
441 /// to the edge of the texture.
442 /// - destinationBuffer: An ``MTLBuffer`` instance the command copies data to.
443 /// - destinationOffset: A byte offset within `destinationBuffer` the command copies to. The value
444 /// you provide as this argument needs to be a multiple of `sourceTexture's` pixel size,
445 /// in bytes.
446 /// - destinationBytesPerRow: The number of bytes between adjacent rows of pixels in `destinationBuffer`.
447 /// This value must be a multiple of `sourceTexture's` pixel size, in bytes,
448 /// and less than or equal to the product of `sourceTexture's` pixel size,
449 /// in bytes, and the largest pixel width `sourceTexture’s` type allows. If
450 /// `sourceTexture` uses a compressed pixel format, set `destinationBytesPerRow`
451 /// to the number of bytes between the starts of two row blocks.
452 /// - destinationBytesPerImage: The number of bytes between each 2D image of a 3D texture. This value must
453 /// be a multiple of `sourceTexture's` pixel size, in bytes. Set this value to
454 /// `0` if `sourceSize's` ``MTLSize/depth`` value is `1`.
455 /// - options: A ``MTLBlitOption`` value that applies to textures with applicable pixel
456 /// formats, such as combined depth/stencil or PVRTC formats. If `sourceTexture's`
457 /// ``MTLTexture/pixelFormat`` is a combined depth/stencil format, set `options`
458 /// to either ``MTLBlitOption/MTLBlitOptionDepthFromDepthStencil`` or
459 /// ``MTLBlitOption/MTLBlitOptionStencilFromDepthStencil``, but not both.
460 /// If `sourceTexture's` ``MTLTexture/pixelFormat`` is a PVRTC format, set
461 /// `options` to ``MTLBlitOption/MTLBlitOptionRowLinearPVRTC``.
462 ///
463 /// # Safety
464 ///
465 /// - `source_texture` may need to be synchronized.
466 /// - `source_texture` may be unretained, you must ensure it is kept alive while in use.
467 /// - `sourceSize` might not be bounds-checked.
468 /// - `destination_buffer` may need to be synchronized.
469 /// - `destination_buffer` may be unretained, you must ensure it is kept alive while in use.
470 /// - `destination_buffer` contents should be of the correct type.
471 /// - `destinationOffset` might not be bounds-checked.
472 #[unsafe(method(copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:))]
473 #[unsafe(method_family = none)]
474 unsafe fn copyFromTexture_sourceSlice_sourceLevel_sourceOrigin_sourceSize_toBuffer_destinationOffset_destinationBytesPerRow_destinationBytesPerImage_options(
475 &self,
476 source_texture: &ProtocolObject<dyn MTLTexture>,
477 source_slice: NSUInteger,
478 source_level: NSUInteger,
479 source_origin: MTLOrigin,
480 source_size: MTLSize,
481 destination_buffer: &ProtocolObject<dyn MTLBuffer>,
482 destination_offset: NSUInteger,
483 destination_bytes_per_row: NSUInteger,
484 destination_bytes_per_image: NSUInteger,
485 options: MTLBlitOption,
486 );
487
488 #[cfg(all(
489 feature = "MTLAllocation",
490 feature = "MTLBuffer",
491 feature = "MTLResource"
492 ))]
493 /// Encodes a command that copies data from a buffer instance into another.
494 ///
495 /// - Parameters:
496 /// - sourceBuffer: An ``MTLBuffer`` instance the command copies data from.
497 /// - sourceOffset: A byte offset within `sourceBuffer` the command copies from.
498 /// - destinationBuffer: An ``MTLBuffer`` instance the command copies data to.
499 /// - destinationOffset: A byte offset within `destinationBuffer` the command copies to.
500 /// - size: The number of bytes the command copies from `sourceBuffer` to `destinationBuffer`.
501 ///
502 /// # Safety
503 ///
504 /// - `source_buffer` may need to be synchronized.
505 /// - `source_buffer` may be unretained, you must ensure it is kept alive while in use.
506 /// - `source_buffer` contents should be of the correct type.
507 /// - `sourceOffset` might not be bounds-checked.
508 /// - `destination_buffer` may need to be synchronized.
509 /// - `destination_buffer` may be unretained, you must ensure it is kept alive while in use.
510 /// - `destination_buffer` contents should be of the correct type.
511 /// - `destinationOffset` might not be bounds-checked.
512 /// - `size` might not be bounds-checked.
513 #[unsafe(method(copyFromBuffer:sourceOffset:toBuffer:destinationOffset:size:))]
514 #[unsafe(method_family = none)]
515 unsafe fn copyFromBuffer_sourceOffset_toBuffer_destinationOffset_size(
516 &self,
517 source_buffer: &ProtocolObject<dyn MTLBuffer>,
518 source_offset: NSUInteger,
519 destination_buffer: &ProtocolObject<dyn MTLBuffer>,
520 destination_offset: NSUInteger,
521 size: NSUInteger,
522 );
523
524 #[cfg(all(
525 feature = "MTLAllocation",
526 feature = "MTLBuffer",
527 feature = "MTLResource",
528 feature = "MTLTexture",
529 feature = "MTLTypes"
530 ))]
531 /// Encodes a command to copy image data from a buffer instance into a texture.
532 ///
533 /// - Parameters:
534 /// - sourceBuffer: A ``MTLBuffer`` instance the command copies data from.
535 /// - sourceOffset: A byte offset within `sourceBuffer` the command copies from. Set this value to
536 /// a multiple of `destinationTexture's` pixel size, in bytes.
537 /// - sourceBytesPerRow: The number of bytes between adjacent rows of pixels in `sourceBuffer`. Set this value to
538 /// a multiple of `destinationTexture's` pixel size, in bytes, and less than or equal to
539 /// the product of `destinationTexture's` pixel size, in bytes, and the largest pixel width
540 /// `destinationTexture's` type allows. If `destinationTexture` uses a compressed pixel format,
541 /// set `sourceBytesPerRow` to the number of bytes between the starts of two row blocks.
542 /// - sourceBytesPerImage: The number of bytes between each 2D image of a 3D texture. Set this value to a
543 /// multiple of `destinationTexture's` pixel size, in bytes, or `0`
544 /// if `sourceSize's` ``MTLSize/depth`` value is `1`.
545 /// - sourceSize: A ``MTLSize`` instance that represents the size of the region in
546 /// `destinationTexture`, in pixels, that the command copies data to, starting at
547 /// `destinationOrigin`. Assign `1` to each dimension that’s not relevant to
548 /// `destinationTexture`. If `destinationTexture` uses a compressed pixel format,
549 /// set `sourceSize` to a multiple of `destinationTexture's` ``MTLTexture/pixelFormat``
550 /// block size. If the block extends outside the bounds of the texture, clamp
551 /// `sourceSize` to the edge of the texture.
552 /// - destinationTexture: An ``MTLTexture`` instance the command copies data to. In order to copy the contents into
553 /// the destination texture, set its ``MTLTexture/framebufferOnly`` property to
554 /// <doc
555 /// ://com.apple.documentation/documentation/swift/false> and don't
556 /// use a combined depth/stencil ``MTLTexture/pixelFormat``.
557 /// - destinationSlice: A slice within `destinationTexture` the command uses as its starting point for
558 /// copying data to. Set this to `0` if `destinationTexture` isn’t a texture array
559 /// or a cube texture.
560 /// - destinationLevel: A mipmap level within `destinationTexture` the command copies data to.
561 /// - destinationOrigin: An ``MTLOrigin`` instance that represents a location within `destinationTexture`
562 /// that the command begins copying data to. Assign `0` to each dimension that’s not
563 /// relevant to `destinationTexture`.
564 ///
565 /// # Safety
566 ///
567 /// - `source_buffer` may need to be synchronized.
568 /// - `source_buffer` may be unretained, you must ensure it is kept alive while in use.
569 /// - `source_buffer` contents should be of the correct type.
570 /// - `sourceOffset` might not be bounds-checked.
571 /// - `sourceSize` might not be bounds-checked.
572 /// - `destination_texture` may need to be synchronized.
573 /// - `destination_texture` may be unretained, you must ensure it is kept alive while in use.
574 #[unsafe(method(copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:))]
575 #[unsafe(method_family = none)]
576 unsafe fn copyFromBuffer_sourceOffset_sourceBytesPerRow_sourceBytesPerImage_sourceSize_toTexture_destinationSlice_destinationLevel_destinationOrigin(
577 &self,
578 source_buffer: &ProtocolObject<dyn MTLBuffer>,
579 source_offset: NSUInteger,
580 source_bytes_per_row: NSUInteger,
581 source_bytes_per_image: NSUInteger,
582 source_size: MTLSize,
583 destination_texture: &ProtocolObject<dyn MTLTexture>,
584 destination_slice: NSUInteger,
585 destination_level: NSUInteger,
586 destination_origin: MTLOrigin,
587 );
588
589 #[cfg(all(
590 feature = "MTLAllocation",
591 feature = "MTLBlitCommandEncoder",
592 feature = "MTLBuffer",
593 feature = "MTLResource",
594 feature = "MTLTexture",
595 feature = "MTLTypes"
596 ))]
597 /// Encodes a command to copy image data from a buffer into a texture with options for special texture formats.
598 ///
599 /// - Parameters:
600 /// - sourceBuffer: An ``MTLBuffer`` instance the command copies data from.
601 /// - sourceOffset: A byte offset within `sourceBuffer` the command copies from. Set this value to
602 /// a multiple of `destinationTexture's` pixel size, in bytes.
603 /// - sourceBytesPerRow: The number of bytes between adjacent rows of pixels in `sourceBuffer`. Set this value to
604 /// a multiple of `destinationTexture's` pixel size, in bytes, and less than or equal to
605 /// the product of `destinationTexture's` pixel size, in bytes, and the largest pixel width
606 /// `destinationTexture's` type allows. If `destinationTexture` uses a compressed pixel format,
607 /// set `sourceBytesPerRow` to the number of bytes between the starts of two row blocks.
608 /// - sourceBytesPerImage: The number of bytes between each 2D image of a 3D texture. Set this value to a
609 /// multiple of `destinationTexture's` pixel size, in bytes, or `0`
610 /// if `sourceSize's` ``MTLSize/depth`` value is `1`.
611 /// - sourceSize: An ``MTLSize`` instance that represents the size of the region in
612 /// `destinationTexture`, in pixels, that the command copies data to, starting at
613 /// `destinationOrigin`. Assign `1` to each dimension that’s not relevant to
614 /// `destinationTexture`. If `destinationTexture` uses a compressed pixel format,
615 /// set `sourceSize` to a multiple of `destinationTexture's` ``MTLTexture/pixelFormat``
616 /// block size. If the block extends outside the bounds of the texture, clamp
617 /// `sourceSize` to the edge of the texture.
618 /// - destinationTexture: An ``MTLTexture`` instance the command copies data to. In order to copy the contents into
619 /// the destination texture, set its ``MTLTexture/framebufferOnly`` property to
620 /// <doc
621 /// ://com.apple.documentation/documentation/swift/false> and don't
622 /// use a combined depth/stencil ``MTLTexture/pixelFormat``.
623 /// - destinationSlice: A slice within `destinationTexture` the command uses as its starting point for
624 /// copying data to. Set this to `0` if `destinationTexture` isn’t a texture array
625 /// or a cube texture.
626 /// - destinationLevel: A mipmap level within `destinationTexture` the command copies data to.
627 /// - destinationOrigin: An ``MTLOrigin`` instance that represents a location within `destinationTexture`
628 /// that the command begins copying data to. Assign `0` to each dimension that’s not
629 /// relevant to `destinationTexture`.
630 /// - options: An ``MTLBlitOption`` value that applies to textures with applicable pixel formats,
631 /// such as combined depth/stencil or PVRTC formats. If `destinationTexture's`
632 /// ``MTLTexture/pixelFormat`` is a combined depth/stencil format, set `options` to
633 /// either ``MTLBlitOption/MTLBlitOptionDepthFromDepthStencil`` or
634 /// ``MTLBlitOption/MTLBlitOptionStencilFromDepthStencil``, but not both.
635 /// If `destinationTexture's` ``MTLTexture/pixelFormat`` is a PVRTC format, set
636 /// `options` to ``MTLBlitOption/MTLBlitOptionRowLinearPVRTC``.
637 ///
638 /// # Safety
639 ///
640 /// - `source_buffer` may need to be synchronized.
641 /// - `source_buffer` may be unretained, you must ensure it is kept alive while in use.
642 /// - `source_buffer` contents should be of the correct type.
643 /// - `sourceOffset` might not be bounds-checked.
644 /// - `sourceSize` might not be bounds-checked.
645 /// - `destination_texture` may need to be synchronized.
646 /// - `destination_texture` may be unretained, you must ensure it is kept alive while in use.
647 #[unsafe(method(copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:options:))]
648 #[unsafe(method_family = none)]
649 unsafe fn copyFromBuffer_sourceOffset_sourceBytesPerRow_sourceBytesPerImage_sourceSize_toTexture_destinationSlice_destinationLevel_destinationOrigin_options(
650 &self,
651 source_buffer: &ProtocolObject<dyn MTLBuffer>,
652 source_offset: NSUInteger,
653 source_bytes_per_row: NSUInteger,
654 source_bytes_per_image: NSUInteger,
655 source_size: MTLSize,
656 destination_texture: &ProtocolObject<dyn MTLTexture>,
657 destination_slice: NSUInteger,
658 destination_level: NSUInteger,
659 destination_origin: MTLOrigin,
660 options: MTLBlitOption,
661 );
662
663 #[cfg(all(
664 feature = "MTLAllocation",
665 feature = "MTLResource",
666 feature = "MTLTensor"
667 ))]
668 /// Encodes a command to copy data from a tensor instance into another.
669 ///
670 /// If the `sourceTensor` and `destinationTensor` instances are not aliasable, this command applies the correct reshapes
671 /// to enable this operation.
672 ///
673 /// - Parameters:
674 /// - sourceTensor: An ``MTLTensor`` instance the command copies data from.
675 /// - sourceSlice: The slice of `sourceTensor` from which Metal copies data.
676 /// - destinationTensor: An ``MTLTensor`` instance the command copies data to.
677 /// - destinationSlice: The slice of `destinationTensor` to which Metal copies data.
678 ///
679 /// # Safety
680 ///
681 /// - `source_tensor` may need to be synchronized.
682 /// - `source_tensor` may be unretained, you must ensure it is kept alive while in use.
683 /// - `destination_tensor` may need to be synchronized.
684 /// - `destination_tensor` may be unretained, you must ensure it is kept alive while in use.
685 #[unsafe(method(copyFromTensor:sourceOrigin:sourceDimensions:toTensor:destinationOrigin:destinationDimensions:))]
686 #[unsafe(method_family = none)]
687 unsafe fn copyFromTensor_sourceOrigin_sourceDimensions_toTensor_destinationOrigin_destinationDimensions(
688 &self,
689 source_tensor: &ProtocolObject<dyn MTLTensor>,
690 source_origin: &MTLTensorExtents,
691 source_dimensions: &MTLTensorExtents,
692 destination_tensor: &ProtocolObject<dyn MTLTensor>,
693 destination_origin: &MTLTensorExtents,
694 destination_dimensions: &MTLTensorExtents,
695 );
696
697 #[cfg(all(
698 feature = "MTLAllocation",
699 feature = "MTLResource",
700 feature = "MTLTexture"
701 ))]
702 /// Encodes a command that generates mipmaps for a texture instance from the base mipmap level up to the highest
703 /// mipmap level.
704 ///
705 /// This method generates mipmaps for a mipmapped texture. The texture you provide needs to have a
706 /// ``MTLTexture/mipmapLevelCount`` greater than `1`, and a color-renderable or color-filterable
707 /// ``MTLTexture/pixelFormat``.
708 ///
709 /// - Parameter texture: A mipmapped, color-renderable or color-filterable ``MTLTexture`` instance the command generates mipmaps for.
710 ///
711 /// # Safety
712 ///
713 /// - `texture` may need to be synchronized.
714 /// - `texture` may be unretained, you must ensure it is kept alive while in use.
715 #[unsafe(method(generateMipmapsForTexture:))]
716 #[unsafe(method_family = none)]
717 unsafe fn generateMipmapsForTexture(&self, texture: &ProtocolObject<dyn MTLTexture>);
718
719 #[cfg(all(
720 feature = "MTLAllocation",
721 feature = "MTLBuffer",
722 feature = "MTLResource"
723 ))]
724 /// Encodes a command that fills a buffer with a constant value for each byte.
725 ///
726 /// - Parameters:
727 /// - buffer: A ``MTLBuffer`` instance for which this command assigns each byte in a range to a value.
728 /// - range: A range of bytes within `buffer` the command assigns value to. When calling this method, pass in a
729 /// range with a length greater than `0`.
730 /// - value: The value to write to each byte.
731 ///
732 /// # Safety
733 ///
734 /// - `buffer` may need to be synchronized.
735 /// - `buffer` may be unretained, you must ensure it is kept alive while in use.
736 /// - `buffer` contents should be of the correct type.
737 /// - `range` might not be bounds-checked.
738 #[unsafe(method(fillBuffer:range:value:))]
739 #[unsafe(method_family = none)]
740 unsafe fn fillBuffer_range_value(
741 &self,
742 buffer: &ProtocolObject<dyn MTLBuffer>,
743 range: NSRange,
744 value: u8,
745 );
746
747 #[cfg(all(
748 feature = "MTLAllocation",
749 feature = "MTLResource",
750 feature = "MTLTexture"
751 ))]
752 /// Encodes a command that modifies the contents of a texture to improve the performance of GPU accesses
753 /// to its contents.
754 ///
755 /// Optimizing a texture for GPU access may affect the performance of CPU accesses, however, the data the CPU
756 /// retrieves from the texture remains consistent.
757 ///
758 /// You typically run this command for:
759 /// * Textures the GPU accesses for an extended period of time.
760 /// * Textures with a ``MTLTextureDescriptor/storageMode`` property that's ``MTLStorageMode/MTLStorageModeShared`` or
761 /// ``MTLStorageMode/MTLStorageModeManaged``.
762 ///
763 /// - Parameter texture: A ``MTLTexture`` instance the command optimizes for GPU access.
764 ///
765 /// # Safety
766 ///
767 /// - `texture` may need to be synchronized.
768 /// - `texture` may be unretained, you must ensure it is kept alive while in use.
769 #[unsafe(method(optimizeContentsForGPUAccess:))]
770 #[unsafe(method_family = none)]
771 unsafe fn optimizeContentsForGPUAccess(&self, texture: &ProtocolObject<dyn MTLTexture>);
772
773 #[cfg(all(
774 feature = "MTLAllocation",
775 feature = "MTLResource",
776 feature = "MTLTexture"
777 ))]
778 /// Encodes a command that modifies the contents of a texture instance to improve the performance of GPU accesses
779 /// to its contents in a specific region.
780 ///
781 /// Optimizing a texture for GPU access may affect the performance of CPU accesses, however, the data the CPU
782 /// retrieves from the texture remains consistent.
783 ///
784 /// You typically run this command for:
785 /// * Textures the GPU accesses for an extended period of time.
786 /// * Textures with a ``MTLTextureDescriptor/storageMode`` property that's ``MTLStorageMode/MTLStorageModeShared`` or
787 /// ``MTLStorageMode/MTLStorageModeManaged``.
788 ///
789 /// - Parameters:
790 /// - texture: A ``MTLTexture`` the command optimizes for GPU access.
791 /// - slice: A slice within `texture`.
792 /// - level: A mipmap level within `texture`.
793 ///
794 /// # Safety
795 ///
796 /// - `texture` may need to be synchronized.
797 /// - `texture` may be unretained, you must ensure it is kept alive while in use.
798 #[unsafe(method(optimizeContentsForGPUAccess:slice:level:))]
799 #[unsafe(method_family = none)]
800 unsafe fn optimizeContentsForGPUAccess_slice_level(
801 &self,
802 texture: &ProtocolObject<dyn MTLTexture>,
803 slice: NSUInteger,
804 level: NSUInteger,
805 );
806
807 #[cfg(all(
808 feature = "MTLAllocation",
809 feature = "MTLResource",
810 feature = "MTLTexture"
811 ))]
812 /// Encodes a command that modifies the contents of a texture to improve the performance of CPU accesses to
813 /// its contents.
814 ///
815 /// Optimizing a texture for CPU access may affect the performance of GPU accesses, however, the data the GPU
816 /// retrieves from the texture remains consistent.
817 ///
818 /// You typically use this command for:
819 /// * Textures the CPU accesses for an extended period of time.
820 /// * Textures with a ``MTLTextureDescriptor/storageMode`` property that's ``MTLStorageMode/MTLStorageModeShared`` or
821 /// ``MTLStorageMode/MTLStorageModeManaged``.
822 ///
823 /// - Parameter texture: A ``MTLTexture`` instance the command optimizes for CPU access.
824 ///
825 /// # Safety
826 ///
827 /// - `texture` may need to be synchronized.
828 /// - `texture` may be unretained, you must ensure it is kept alive while in use.
829 #[unsafe(method(optimizeContentsForCPUAccess:))]
830 #[unsafe(method_family = none)]
831 unsafe fn optimizeContentsForCPUAccess(&self, texture: &ProtocolObject<dyn MTLTexture>);
832
833 #[cfg(all(
834 feature = "MTLAllocation",
835 feature = "MTLResource",
836 feature = "MTLTexture"
837 ))]
838 /// Encodes a command that modifies the contents of a texture to improve the performance of CPU accesses
839 /// to its contents in a specific region.
840 ///
841 /// Optimizing a texture for CPU access may affect the performance of GPU accesses, however, the data the GPU
842 /// retrieves from the texture remains consistent.
843 ///
844 /// You typically use this command for:
845 /// * Textures the CPU accesses for an extended period of time.
846 /// * Textures with a ``MTLTextureDescriptor/storageMode`` property that's ``MTLStorageMode/MTLStorageModeShared`` or
847 /// ``MTLStorageMode/MTLStorageModeManaged``.
848 ///
849 /// - Parameters:
850 /// - texture: A ``MTLTexture`` the command optimizes for CPU access.
851 /// - slice: A slice within `texture`.
852 /// - level: A mipmap level within `texture`.
853 ///
854 /// # Safety
855 ///
856 /// - `texture` may need to be synchronized.
857 /// - `texture` may be unretained, you must ensure it is kept alive while in use.
858 #[unsafe(method(optimizeContentsForCPUAccess:slice:level:))]
859 #[unsafe(method_family = none)]
860 unsafe fn optimizeContentsForCPUAccess_slice_level(
861 &self,
862 texture: &ProtocolObject<dyn MTLTexture>,
863 slice: NSUInteger,
864 level: NSUInteger,
865 );
866
867 #[cfg(all(
868 feature = "MTLAllocation",
869 feature = "MTLIndirectCommandBuffer",
870 feature = "MTLResource"
871 ))]
872 /// Encodes a command that resets a range of commands in an indirect command buffer.
873 ///
874 /// - Parameters:
875 /// - buffer: An ``MTLIndirectCommandBuffer`` the command resets.
876 /// - range: A range of commands within `buffer`.
877 ///
878 /// # Safety
879 ///
880 /// - `buffer` may need to be synchronized.
881 /// - `buffer` may be unretained, you must ensure it is kept alive while in use.
882 /// - `range` might not be bounds-checked.
883 #[unsafe(method(resetCommandsInBuffer:withRange:))]
884 #[unsafe(method_family = none)]
885 unsafe fn resetCommandsInBuffer_withRange(
886 &self,
887 buffer: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
888 range: NSRange,
889 );
890
891 #[cfg(all(
892 feature = "MTLAllocation",
893 feature = "MTLIndirectCommandBuffer",
894 feature = "MTLResource"
895 ))]
896 /// Encodes a command that copies commands from an indirect command buffer into another.
897 ///
898 /// - Parameters:
899 /// - source: An ``MTLIndirectCommandBuffer`` instance from where the command copies.
900 /// - sourceRange: The range of commands in `source` to copy.
901 /// The copy operation requires that the source range starts at a valid execution point.
902 /// - destination: Another ``MTLIndirectCommandBuffer`` instance into which the command copies.
903 /// - destinationIndex: An index in `destination` into where the command copies content to. The copy operation requires
904 /// that the destination index is a valid execution point with enough space left in `destination`
905 /// to accommodate `sourceRange.count` commands.
906 ///
907 /// # Safety
908 ///
909 /// - `source` may need to be synchronized.
910 /// - `source` may be unretained, you must ensure it is kept alive while in use.
911 /// - `sourceRange` might not be bounds-checked.
912 /// - `destination` may need to be synchronized.
913 /// - `destination` may be unretained, you must ensure it is kept alive while in use.
914 /// - `destinationIndex` might not be bounds-checked.
915 #[unsafe(method(copyIndirectCommandBuffer:sourceRange:destination:destinationIndex:))]
916 #[unsafe(method_family = none)]
917 unsafe fn copyIndirectCommandBuffer_sourceRange_destination_destinationIndex(
918 &self,
919 source: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
920 source_range: NSRange,
921 destination: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
922 destination_index: NSUInteger,
923 );
924
925 #[cfg(all(
926 feature = "MTLAllocation",
927 feature = "MTLIndirectCommandBuffer",
928 feature = "MTLResource"
929 ))]
930 /// Encode a command to attempt to improve the performance of a range of commands within an indirect command buffer.
931 ///
932 /// - Parameters:
933 /// - indirectCommandBuffer: An ``MTLIndirectCommandBuffer`` instance that this command optimizes.
934 /// - range: A range of commands within `indirectCommandBuffer`.
935 ///
936 /// # Safety
937 ///
938 /// - `indirect_command_buffer` may need to be synchronized.
939 /// - `indirect_command_buffer` may be unretained, you must ensure it is kept alive while in use.
940 /// - `range` might not be bounds-checked.
941 #[unsafe(method(optimizeIndirectCommandBuffer:withRange:))]
942 #[unsafe(method_family = none)]
943 unsafe fn optimizeIndirectCommandBuffer_withRange(
944 &self,
945 indirect_command_buffer: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
946 range: NSRange,
947 );
948
949 #[cfg(feature = "MTL4ArgumentTable")]
950 /// Sets an argument table for the compute shader stage of this pipeline.
951 ///
952 /// Metal takes a snapshot of the resources in the argument table when you make dispatch or execute calls on
953 /// this encoder instance. Metal makes the snapshot contents available to the compute shader function of the
954 /// current pipeline state.
955 ///
956 /// - Parameters:
957 /// - argumentTable: A ``MTL4ArgumentTable`` to set on the command encoder.
958 #[unsafe(method(setArgumentTable:))]
959 #[unsafe(method_family = none)]
960 fn setArgumentTable(&self, argument_table: Option<&ProtocolObject<dyn MTL4ArgumentTable>>);
961
962 #[cfg(all(
963 feature = "MTL4AccelerationStructure",
964 feature = "MTL4BufferRange",
965 feature = "MTLAccelerationStructure",
966 feature = "MTLAllocation",
967 feature = "MTLGPUAddress",
968 feature = "MTLResource"
969 ))]
970 /// Encodes an acceleration structure build into the command buffer.
971 ///
972 /// Before you build an instance acceleration structure, you are responsible for ensuring the build operations for all
973 /// primitive acceleration structures is complete. The built acceleration structure doesn't retain any references to
974 /// the input buffers of the descriptor, such as the vertex buffer or instance buffer, among others.
975 ///
976 /// The acceleration structure build process may continue as long as the command buffer is not completed. However,
977 /// you can safely encode ray tracing work against the acceleration structure if you schedule and synchronize the
978 /// command buffers that contain this ray tracing work such that the command buffer with the build command is complete
979 /// by the time ray tracing starts.
980 ///
981 /// You are responsible for ensuring that the acceleration structure and scratch buffer are at least the size
982 /// that the query ``MTLDevice/accelerationStructureSizesWithDescriptor:`` returns.
983 ///
984 /// Use an instance of ``MTLResidencySet`` to mark residency of the scratch buffer the `scratchBuffer` parameter references,
985 /// as well as for all the primitive acceleration structures you directly and indirectly reference.
986 ///
987 /// - Parameters:
988 /// - accelerationStructure: Acceleration structure storage to build into.
989 /// - descriptor: A descriptor for the acceleration structure Metal builds.
990 /// - scratchBuffer: Scratch buffer Metal can use while building the acceleration structure.
991 /// Metal may overwrite the contents of this buffer, and you should consider
992 /// them "undefined" after the refit operation starts and completes.
993 ///
994 /// # Safety
995 ///
996 /// - `acceleration_structure` may need to be synchronized.
997 /// - `acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
998 #[unsafe(method(buildAccelerationStructure:descriptor:scratchBuffer:))]
999 #[unsafe(method_family = none)]
1000 unsafe fn buildAccelerationStructure_descriptor_scratchBuffer(
1001 &self,
1002 acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1003 descriptor: &MTL4AccelerationStructureDescriptor,
1004 scratch_buffer: MTL4BufferRange,
1005 );
1006
1007 #[cfg(all(
1008 feature = "MTL4AccelerationStructure",
1009 feature = "MTL4BufferRange",
1010 feature = "MTLAccelerationStructure",
1011 feature = "MTLAllocation",
1012 feature = "MTLGPUAddress",
1013 feature = "MTLResource"
1014 ))]
1015 /// Encodes an acceleration structure refit into the command buffer.
1016 ///
1017 /// You refit an acceleration structure to update it when the geometry it references changes. This operation is typically
1018 /// much faster than rebuilding the acceleration structure from scratch. The trade off is that after you refit the
1019 /// acceleration structure, its quality, as well as the performance of any subsequent ray tracing operation degrades,
1020 /// depending on how much the geometry changes.
1021 ///
1022 /// After certain operations, refitting an acceleration structure may not be possible, for example, after adding or
1023 /// removing geometry.
1024 ///
1025 /// When you refit an acceleration structure, you can do so in place, by specifying the same source and destination
1026 /// acceleration structures, or by providing a `nil` destination acceleration structure. If the source and destination
1027 /// acceleration structures aren't the same, then you are responsible for ensuring they don't overlap in memory.
1028 ///
1029 /// Typically, the destination acceleration structure is at least as large as the source acceleration structure,
1030 /// except in cases where you compact the source acceleration structure. In this case, you need to allocate the
1031 /// destination acceleration to be at least as large as the compacted size of the source acceleration structure.
1032 ///
1033 /// The scratch buffer you provide for the refit operation needs to be at least as large as the size that the query
1034 /// ``MTLDevice/accelerationStructureSizesWithDescriptor:`` returns. If the size this query returns is zero, you
1035 /// can omit providing a scratch buffer by passing `0` as the address to the `scratchBuffer` parameter.
1036 ///
1037 /// Use an instance of ``MTLResidencySet`` to mark residency of the scratch buffer the `scratchBuffer` parameter references,
1038 /// as well as for all the instance and primitive acceleration structures you directly and indirectly reference.
1039 ///
1040 /// - Parameters:
1041 /// - sourceAccelerationStructure: Acceleration structure to refit.
1042 /// - descriptor: A descriptor for the acceleration structure to refit.
1043 /// - destinationAccelerationStructure: Acceleration structure to store the refit result into.
1044 /// If `destinationAccelerationStructure` is `nil`, Metal performs an in-place
1045 /// refit operation of the `sourceAccelerationStructure`.
1046 /// - scratchBuffer: Scratch buffer Metal can use while refitting the acceleration structure.
1047 /// Metal may overwrite the contents of this buffer, and you should consider
1048 /// them "undefined" after the refit operation starts and completes.
1049 ///
1050 /// # Safety
1051 ///
1052 /// - `source_acceleration_structure` may need to be synchronized.
1053 /// - `source_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1054 /// - `destination_acceleration_structure` may need to be synchronized.
1055 /// - `destination_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1056 #[unsafe(method(refitAccelerationStructure:descriptor:destination:scratchBuffer:))]
1057 #[unsafe(method_family = none)]
1058 unsafe fn refitAccelerationStructure_descriptor_destination_scratchBuffer(
1059 &self,
1060 source_acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1061 descriptor: &MTL4AccelerationStructureDescriptor,
1062 destination_acceleration_structure: Option<
1063 &ProtocolObject<dyn MTLAccelerationStructure>,
1064 >,
1065 scratch_buffer: MTL4BufferRange,
1066 );
1067
1068 #[cfg(all(
1069 feature = "MTL4AccelerationStructure",
1070 feature = "MTL4BufferRange",
1071 feature = "MTLAccelerationStructure",
1072 feature = "MTLAllocation",
1073 feature = "MTLGPUAddress",
1074 feature = "MTLResource"
1075 ))]
1076 /// Encodes an acceleration structure refit operation into the command buffer, providing additional options.
1077 ///
1078 /// You refit an acceleration structure to update it when the geometry it references changes. This operation is typically
1079 /// much faster than rebuilding the acceleration structure from scratch. The trade off is that after you refit the
1080 /// acceleration structure, its quality, as well as the performance of any subsequent ray tracing operation degrades,
1081 /// depending on how much the geometry changes.
1082 ///
1083 /// After certain operations, refitting an acceleration structure may not be possible, for example, after adding or
1084 /// removing geometry.
1085 ///
1086 /// When you refit an acceleration structure, you can do so in place, by specifying the same source and destination
1087 /// acceleration structures, or by providing a `nil` destination acceleration structure. If the source and destination
1088 /// acceleration structures aren't the same, then you are responsible for ensuring they don't overlap in memory.
1089 ///
1090 /// Typically, the destination acceleration structure is at least as large as the source acceleration structure,
1091 /// except in cases where you compact the source acceleration structure. In this case, you need to allocate the
1092 /// destination acceleration to be at least as large as the compacted size of the source acceleration structure.
1093 ///
1094 /// The scratch buffer you provide for the refit operation needs to be at least as large as the size that the query
1095 /// ``MTLDevice/accelerationStructureSizesWithDescriptor:`` returns. If the size this query returns is zero, you
1096 /// can omit providing a scratch buffer by passing `0` as the address to the `scratchBuffer` parameter.
1097 ///
1098 /// Use an instance of ``MTLResidencySet`` to mark residency of the scratch buffer the `scratchBuffer` parameter references,
1099 /// as well as for all the instance and primitive acceleration structures you directly and indirectly reference.
1100 ///
1101 /// - Parameters:
1102 /// - sourceAccelerationStructure: Acceleration structure to refit.
1103 /// - descriptor: A descriptor for the acceleration structure to refit.
1104 /// - destinationAccelerationStructure: Acceleration structure to store the refit result into.
1105 /// If `destinationAccelerationStructure` is `nil`, Metal performs an in-place
1106 /// refit operation of the `sourceAccelerationStructure`.
1107 /// - scratchBuffer: Scratch buffer Metal can use while refitting the acceleration structure.
1108 /// Metal may overwrite the contents of this buffer, and you should consider
1109 /// them "undefined" after the refit operation starts and completes.
1110 /// - options: Options specifying the elements of the acceleration structure to refit.
1111 ///
1112 /// # Safety
1113 ///
1114 /// - `source_acceleration_structure` may need to be synchronized.
1115 /// - `source_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1116 /// - `destination_acceleration_structure` may need to be synchronized.
1117 /// - `destination_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1118 #[unsafe(method(refitAccelerationStructure:descriptor:destination:scratchBuffer:options:))]
1119 #[unsafe(method_family = none)]
1120 unsafe fn refitAccelerationStructure_descriptor_destination_scratchBuffer_options(
1121 &self,
1122 source_acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1123 descriptor: &MTL4AccelerationStructureDescriptor,
1124 destination_acceleration_structure: Option<
1125 &ProtocolObject<dyn MTLAccelerationStructure>,
1126 >,
1127 scratch_buffer: MTL4BufferRange,
1128 options: MTLAccelerationStructureRefitOptions,
1129 );
1130
1131 #[cfg(all(
1132 feature = "MTLAccelerationStructure",
1133 feature = "MTLAllocation",
1134 feature = "MTLResource"
1135 ))]
1136 /// Encodes an acceleration structure copy operation into the command buffer.
1137 ///
1138 /// You are responsible for ensuring the source and destination acceleration structures don't overlap in memory.
1139 /// If this is an instance acceleration structure, Metal preserves references to the primitive acceleration structures
1140 /// it references.
1141 ///
1142 /// Typically, the destination acceleration structure is at least as large as the source acceleration structure,
1143 /// except in cases where you compact the source acceleration structure. In this case, you need to allocate the
1144 /// destination acceleration to be at least as large as the compacted size of the source acceleration structure.
1145 ///
1146 /// - Parameters:
1147 /// - sourceAccelerationStructure: Acceleration structure to copy from.
1148 /// - destinationAccelerationStructure: Acceleration structure to copy to.
1149 ///
1150 /// # Safety
1151 ///
1152 /// - `source_acceleration_structure` may need to be synchronized.
1153 /// - `source_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1154 /// - `destination_acceleration_structure` may need to be synchronized.
1155 /// - `destination_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1156 #[unsafe(method(copyAccelerationStructure:toAccelerationStructure:))]
1157 #[unsafe(method_family = none)]
1158 unsafe fn copyAccelerationStructure_toAccelerationStructure(
1159 &self,
1160 source_acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1161 destination_acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1162 );
1163
1164 #[cfg(all(
1165 feature = "MTL4BufferRange",
1166 feature = "MTLAccelerationStructure",
1167 feature = "MTLAllocation",
1168 feature = "MTLGPUAddress",
1169 feature = "MTLResource"
1170 ))]
1171 /// Encodes a command to compute the size an acceleration structure can compact into, writing the result
1172 /// into a buffer.
1173 ///
1174 /// This size is potentially smaller than the acceleration structure. To perform compaction, you typically read
1175 /// this size from the buffer once the command buffer completes. You then use it to allocate a new, potentially
1176 /// smaller acceleration structure. Finally, you call the ``copyAndCompactAccelerationStructure:toAccelerationStructure:``
1177 /// method to perform the copy.
1178 ///
1179 /// - Parameters:
1180 /// - accelerationStructure: Source acceleration structure.
1181 /// - buffer: Destination size buffer. Metal writes the compacted size as a 64-bit unsigned integer
1182 /// value, representing the compacted size in bytes.
1183 ///
1184 /// # Safety
1185 ///
1186 /// - `acceleration_structure` may need to be synchronized.
1187 /// - `acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1188 /// - This might not be bounds-checked.
1189 #[unsafe(method(writeCompactedAccelerationStructureSize:toBuffer:))]
1190 #[unsafe(method_family = none)]
1191 unsafe fn writeCompactedAccelerationStructureSize_toBuffer(
1192 &self,
1193 acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1194 buffer: MTL4BufferRange,
1195 );
1196
1197 #[cfg(all(
1198 feature = "MTLAccelerationStructure",
1199 feature = "MTLAllocation",
1200 feature = "MTLResource"
1201 ))]
1202 /// Encodes a command to copy and compact an acceleration structure.
1203 ///
1204 /// You are responsible for ensuring that the source and destination acceleration structures don't overlap in memory.
1205 /// If this is an instance acceleration structure, Metal preserves references to primitive acceleration structures it
1206 /// references.
1207 ///
1208 /// This operation requires that the destination acceleration structure is at least as large as the compacted size of
1209 /// the source acceleration structure. You can compute this size by calling the
1210 /// ``writeCompactedAccelerationStructureSize:toBuffer:`` method.
1211 ///
1212 /// - Parameters:
1213 /// - sourceAccelerationStructure: Acceleration structure to copy and compact.
1214 /// - destinationAccelerationStructure: Acceleration structure to copy to.
1215 ///
1216 /// # Safety
1217 ///
1218 /// - `source_acceleration_structure` may need to be synchronized.
1219 /// - `source_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1220 /// - `destination_acceleration_structure` may need to be synchronized.
1221 /// - `destination_acceleration_structure` may be unretained, you must ensure it is kept alive while in use.
1222 #[unsafe(method(copyAndCompactAccelerationStructure:toAccelerationStructure:))]
1223 #[unsafe(method_family = none)]
1224 unsafe fn copyAndCompactAccelerationStructure_toAccelerationStructure(
1225 &self,
1226 source_acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1227 destination_acceleration_structure: &ProtocolObject<dyn MTLAccelerationStructure>,
1228 );
1229
1230 #[cfg(feature = "MTL4Counters")]
1231 /// Writes a GPU timestamp into a heap.
1232 ///
1233 /// The method ensures that any prior work finishes, but doesn't delay any subsequent work.
1234 ///
1235 /// You can alter this command's behavior through the `granularity` parameter.
1236 /// - Pass ``MTL4TimestampGranularity/MTL4TimestampGranularityRelaxed`` to allow Metal to provide timestamps with
1237 /// minimal impact to runtime performance, but with less detail. For example, the command may group all timestamps for
1238 /// a pass together.
1239 /// - Pass ``MTL4TimestampGranularity/MTL4TimestampGranularityPrecise`` to request that Metal provides timestamps
1240 /// with the most detail. This can affect runtime performance.
1241 ///
1242 /// - Parameters:
1243 /// - granularity: ``MTL4TimestampGranularity`` hint to Metal about acceptable the level of precision.
1244 /// - counterHeap: ``MTL4CounterHeap`` to write timestamps into.
1245 /// - index: The index value into which Metal writes the timestamp.
1246 ///
1247 /// # Safety
1248 ///
1249 /// `index` might not be bounds-checked.
1250 #[unsafe(method(writeTimestampWithGranularity:intoHeap:atIndex:))]
1251 #[unsafe(method_family = none)]
1252 unsafe fn writeTimestampWithGranularity_intoHeap_atIndex(
1253 &self,
1254 granularity: MTL4TimestampGranularity,
1255 counter_heap: &ProtocolObject<dyn MTL4CounterHeap>,
1256 index: NSUInteger,
1257 );
1258 }
1259);