objc2_metal/generated/MTLTensor.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
10/// The possible data types for the elements of a tensor.
11///
12/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensordatatype?language=objc)
13// NS_ENUM
14#[repr(transparent)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
16pub struct MTLTensorDataType(pub NSInteger);
17impl MTLTensorDataType {
18 #[doc(alias = "MTLTensorDataTypeNone")]
19 pub const None: Self = Self(0);
20 #[doc(alias = "MTLTensorDataTypeFloat32")]
21 pub const Float32: Self = Self(3);
22 #[doc(alias = "MTLTensorDataTypeFloat16")]
23 pub const Float16: Self = Self(16);
24 #[doc(alias = "MTLTensorDataTypeBFloat16")]
25 pub const BFloat16: Self = Self(121);
26 #[doc(alias = "MTLTensorDataTypeInt8")]
27 pub const Int8: Self = Self(45);
28 #[doc(alias = "MTLTensorDataTypeUInt8")]
29 pub const UInt8: Self = Self(49);
30 #[doc(alias = "MTLTensorDataTypeInt16")]
31 pub const Int16: Self = Self(37);
32 #[doc(alias = "MTLTensorDataTypeUInt16")]
33 pub const UInt16: Self = Self(41);
34 #[doc(alias = "MTLTensorDataTypeInt32")]
35 pub const Int32: Self = Self(29);
36 #[doc(alias = "MTLTensorDataTypeUInt32")]
37 pub const UInt32: Self = Self(33);
38}
39
40unsafe impl Encode for MTLTensorDataType {
41 const ENCODING: Encoding = NSInteger::ENCODING;
42}
43
44unsafe impl RefEncode for MTLTensorDataType {
45 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
46}
47
48extern_class!(
49 /// An array of length matching the rank, holding the dimensions of a tensor.
50 ///
51 /// Supports rank up to ``MTL_TENSOR_MAX_RANK``.
52 ///
53 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensorextents?language=objc)
54 #[unsafe(super(NSObject))]
55 #[derive(Debug, PartialEq, Eq, Hash)]
56 pub struct MTLTensorExtents;
57);
58
59extern_conformance!(
60 unsafe impl NSObjectProtocol for MTLTensorExtents {}
61);
62
63impl MTLTensorExtents {
64 extern_methods!(
65 /// Creates a new tensor extents with the rank and extent values you provide.
66 ///
67 /// Zero rank extents represent scalars. `values` can only be `nil`if `rank` is 0.
68 /// - Parameters:
69 /// - rank: the number of dimensions.
70 /// - values: an array of length `rank` that specifies the size of each dimension. The first dimension is the innermost dimension.
71 /// - Returns: Tensor extents with the rank and extent values you provide. Returns `nil` if `rank` exceeds 0 and `values` is nil or if `rank` exceeds ``MTL_TENSOR_MAX_RANK``.
72 ///
73 /// # Safety
74 ///
75 /// `values` must be a valid pointer or null.
76 #[unsafe(method(initWithRank:values:))]
77 #[unsafe(method_family = init)]
78 pub unsafe fn initWithRank_values(
79 this: Allocated<Self>,
80 rank: NSUInteger,
81 values: *const NSInteger,
82 ) -> Option<Retained<Self>>;
83
84 /// Obtains the rank of the tensor.
85 ///
86 /// The rank represents the number of dimensions.
87 #[unsafe(method(rank))]
88 #[unsafe(method_family = none)]
89 pub fn rank(&self) -> NSUInteger;
90
91 /// Returns the extent at an index.
92 ///
93 /// - Parameters:
94 /// - dimensionIndex: the index of the dimension. The first dimension is the innermost dimension.
95 /// - Returns: the extent at `dimensionIndex`. This method returns -1 if `dimensionIndex` is greater than or equal to `rank`.
96 ///
97 /// # Safety
98 ///
99 /// `dimensionIndex` might not be bounds-checked.
100 #[unsafe(method(extentAtDimensionIndex:))]
101 #[unsafe(method_family = none)]
102 pub unsafe fn extentAtDimensionIndex(&self, dimension_index: NSUInteger) -> NSInteger;
103 );
104}
105
106/// Methods declared on superclass `NSObject`.
107impl MTLTensorExtents {
108 extern_methods!(
109 #[unsafe(method(init))]
110 #[unsafe(method_family = init)]
111 pub fn init(this: Allocated<Self>) -> Retained<Self>;
112
113 #[unsafe(method(new))]
114 #[unsafe(method_family = new)]
115 pub fn new() -> Retained<Self>;
116 );
117}
118
119impl DefaultRetained for MTLTensorExtents {
120 #[inline]
121 fn default_retained() -> Retained<Self> {
122 Self::new()
123 }
124}
125
126extern "C" {
127 /// An error domain for errors that pertain to creating a tensor.
128 ///
129 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensordomain?language=objc)
130 pub static MTLTensorDomain: &'static NSErrorDomain;
131}
132
133/// The error codes that Metal can raise when you create a tensor.
134///
135/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensorerror?language=objc)
136// NS_ENUM
137#[repr(transparent)]
138#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
139pub struct MTLTensorError(pub NSInteger);
140impl MTLTensorError {
141 #[doc(alias = "MTLTensorErrorNone")]
142 pub const None: Self = Self(0);
143 #[doc(alias = "MTLTensorErrorInternalError")]
144 pub const InternalError: Self = Self(1);
145 #[doc(alias = "MTLTensorErrorInvalidDescriptor")]
146 pub const InvalidDescriptor: Self = Self(2);
147}
148
149unsafe impl Encode for MTLTensorError {
150 const ENCODING: Encoding = NSInteger::ENCODING;
151}
152
153unsafe impl RefEncode for MTLTensorError {
154 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
155}
156
157/// The type that represents the different contexts for a tensor.
158///
159/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensorusage?language=objc)
160// NS_OPTIONS
161#[repr(transparent)]
162#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
163pub struct MTLTensorUsage(pub NSUInteger);
164bitflags::bitflags! {
165 impl MTLTensorUsage: NSUInteger {
166/// A tensor context that applies to compute encoders.
167///
168/// You can use tensors with this context in ``MTL4ComputeCommandEncoder`` or ``MTLComputeCommandEncoder`` instances.
169 #[doc(alias = "MTLTensorUsageCompute")]
170 const Compute = 1<<0;
171/// A tensor context that applies to render encoders.
172///
173/// You can use tensors with this context in ``MTL4RenderCommandEncoder`` or ``MTLRenderCommandEncoder`` instances.
174 #[doc(alias = "MTLTensorUsageRender")]
175 const Render = 1<<1;
176/// A tensor context that applies to machine learning encoders.
177///
178/// You can use tensors with this context in ``MTL4MachineLearningCommandEncoder`` instances.
179 #[doc(alias = "MTLTensorUsageMachineLearning")]
180 const MachineLearning = 1<<2;
181 }
182}
183
184unsafe impl Encode for MTLTensorUsage {
185 const ENCODING: Encoding = NSUInteger::ENCODING;
186}
187
188unsafe impl RefEncode for MTLTensorUsage {
189 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
190}
191
192extern_class!(
193 /// A configuration type for creating new tensor instances.
194 ///
195 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensordescriptor?language=objc)
196 #[unsafe(super(NSObject))]
197 #[derive(Debug, PartialEq, Eq, Hash)]
198 pub struct MTLTensorDescriptor;
199);
200
201extern_conformance!(
202 unsafe impl NSCopying for MTLTensorDescriptor {}
203);
204
205unsafe impl CopyingHelper for MTLTensorDescriptor {
206 type Result = Self;
207}
208
209extern_conformance!(
210 unsafe impl NSObjectProtocol for MTLTensorDescriptor {}
211);
212
213impl MTLTensorDescriptor {
214 extern_methods!(
215 /// An array of sizes, in elements, one for each dimension of the tensors you create with this descriptor.
216 ///
217 /// The default value of this property is a rank one extents with size one.
218 #[unsafe(method(dimensions))]
219 #[unsafe(method_family = none)]
220 pub fn dimensions(&self) -> Retained<MTLTensorExtents>;
221
222 /// Setter for [`dimensions`][Self::dimensions].
223 ///
224 /// This is [copied][objc2_foundation::NSCopying::copy] when set.
225 #[unsafe(method(setDimensions:))]
226 #[unsafe(method_family = none)]
227 pub fn setDimensions(&self, dimensions: &MTLTensorExtents);
228
229 /// An array of strides, in elements, one for each dimension in the tensors you create with this descriptor, if applicable.
230 ///
231 /// This property only applies to tensors you create from a buffer, otherwise it is nil. You are responsible for ensuring `strides` meets the following requirements:
232 /// - Elements of `strides`are in monotonically non-decreasing order.
233 /// - The first element of `strides` is one.
234 /// - For any `i` larger than zero, `strides[i]` is greater than or equal to `strides[i-1] * dimensions[i-1]`.
235 /// - If `usage` contains ``MTLTensorUsage/MTLTensorUsageMachineLearning``, the second element of `strides` is aligned to 64 bytes, and for any `i` larger than one, `strides[i]` is equal to `strides[i-1] * dimensions[i-1]`.
236 #[unsafe(method(strides))]
237 #[unsafe(method_family = none)]
238 pub fn strides(&self) -> Option<Retained<MTLTensorExtents>>;
239
240 /// Setter for [`strides`][Self::strides].
241 ///
242 /// This is [copied][objc2_foundation::NSCopying::copy] when set.
243 #[unsafe(method(setStrides:))]
244 #[unsafe(method_family = none)]
245 pub fn setStrides(&self, strides: Option<&MTLTensorExtents>);
246
247 /// A data format for the tensors you create with this descriptor.
248 ///
249 /// The default value of this property is ``MTLTensorDataType/MTLTensorDataTypeFloat32``.
250 #[unsafe(method(dataType))]
251 #[unsafe(method_family = none)]
252 pub fn dataType(&self) -> MTLTensorDataType;
253
254 /// Setter for [`dataType`][Self::dataType].
255 #[unsafe(method(setDataType:))]
256 #[unsafe(method_family = none)]
257 pub fn setDataType(&self, data_type: MTLTensorDataType);
258
259 /// A set of contexts in which you can use tensors you create with this descriptor.
260 ///
261 /// The default value for this property is a bitwise `OR` of:
262 /// - ``MTLTensorUsage/MTLTensorUsageRender``
263 /// - ``MTLTensorUsage/MTLTensorUsageCompute``
264 #[unsafe(method(usage))]
265 #[unsafe(method_family = none)]
266 pub fn usage(&self) -> MTLTensorUsage;
267
268 /// Setter for [`usage`][Self::usage].
269 #[unsafe(method(setUsage:))]
270 #[unsafe(method_family = none)]
271 pub fn setUsage(&self, usage: MTLTensorUsage);
272
273 #[cfg(feature = "MTLResource")]
274 /// A packed set of the `storageMode`, `cpuCacheMode` and `hazardTrackingMode` properties.
275 #[unsafe(method(resourceOptions))]
276 #[unsafe(method_family = none)]
277 pub fn resourceOptions(&self) -> MTLResourceOptions;
278
279 #[cfg(feature = "MTLResource")]
280 /// Setter for [`resourceOptions`][Self::resourceOptions].
281 #[unsafe(method(setResourceOptions:))]
282 #[unsafe(method_family = none)]
283 pub fn setResourceOptions(&self, resource_options: MTLResourceOptions);
284
285 #[cfg(feature = "MTLResource")]
286 /// A value that configures the cache mode of CPU mapping of tensors you create with this descriptor.
287 ///
288 /// The default value of this property is ``MTLCPUCacheMode/MTLCPUCacheModeDefaultCache``.
289 #[unsafe(method(cpuCacheMode))]
290 #[unsafe(method_family = none)]
291 pub fn cpuCacheMode(&self) -> MTLCPUCacheMode;
292
293 #[cfg(feature = "MTLResource")]
294 /// Setter for [`cpuCacheMode`][Self::cpuCacheMode].
295 #[unsafe(method(setCpuCacheMode:))]
296 #[unsafe(method_family = none)]
297 pub fn setCpuCacheMode(&self, cpu_cache_mode: MTLCPUCacheMode);
298
299 #[cfg(feature = "MTLResource")]
300 /// A value that configures the memory location and access permissions of tensors you create with this descriptor.
301 ///
302 /// The default value of this property defaults to ``MTLStorageMode/MTLStorageModeShared``.
303 #[unsafe(method(storageMode))]
304 #[unsafe(method_family = none)]
305 pub fn storageMode(&self) -> MTLStorageMode;
306
307 #[cfg(feature = "MTLResource")]
308 /// Setter for [`storageMode`][Self::storageMode].
309 #[unsafe(method(setStorageMode:))]
310 #[unsafe(method_family = none)]
311 pub fn setStorageMode(&self, storage_mode: MTLStorageMode);
312
313 #[cfg(feature = "MTLResource")]
314 /// A value that configures the hazard tracking of tensors you create with this descriptor.
315 ///
316 /// The default value of this property is ``MTLHazardTrackingMode/MTLHazardTrackingModeDefault``.
317 #[unsafe(method(hazardTrackingMode))]
318 #[unsafe(method_family = none)]
319 pub fn hazardTrackingMode(&self) -> MTLHazardTrackingMode;
320
321 #[cfg(feature = "MTLResource")]
322 /// Setter for [`hazardTrackingMode`][Self::hazardTrackingMode].
323 #[unsafe(method(setHazardTrackingMode:))]
324 #[unsafe(method_family = none)]
325 pub fn setHazardTrackingMode(&self, hazard_tracking_mode: MTLHazardTrackingMode);
326 );
327}
328
329/// Methods declared on superclass `NSObject`.
330impl MTLTensorDescriptor {
331 extern_methods!(
332 #[unsafe(method(init))]
333 #[unsafe(method_family = init)]
334 pub fn init(this: Allocated<Self>) -> Retained<Self>;
335
336 #[unsafe(method(new))]
337 #[unsafe(method_family = new)]
338 pub fn new() -> Retained<Self>;
339 );
340}
341
342impl DefaultRetained for MTLTensorDescriptor {
343 #[inline]
344 fn default_retained() -> Retained<Self> {
345 Self::new()
346 }
347}
348
349extern_protocol!(
350 /// A resource representing a multi-dimensional array that you can use with machine learning workloads.
351 ///
352 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtltensor?language=objc)
353 #[cfg(all(feature = "MTLAllocation", feature = "MTLResource"))]
354 pub unsafe trait MTLTensor: MTLResource {
355 #[cfg(feature = "MTLTypes")]
356 /// A handle that represents the GPU resource, which you can store in an argument buffer.
357 #[unsafe(method(gpuResourceID))]
358 #[unsafe(method_family = none)]
359 fn gpuResourceID(&self) -> MTLResourceID;
360
361 #[cfg(feature = "MTLBuffer")]
362 /// A buffer instance this tensor shares its storage with or nil if this tensor does not wrap an underlying buffer.
363 #[unsafe(method(buffer))]
364 #[unsafe(method_family = none)]
365 fn buffer(&self) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>;
366
367 /// An offset, in bytes, into the buffer instance this tensor shares its storage with, or zero if this tensor does not wrap an underlying buffer.
368 #[unsafe(method(bufferOffset))]
369 #[unsafe(method_family = none)]
370 fn bufferOffset(&self) -> NSUInteger;
371
372 /// An array of strides, in elements, one for each dimension of this tensor.
373 ///
374 /// This property only applies if this tensor shares its storage with a buffer, otherwise it's nil.
375 #[unsafe(method(strides))]
376 #[unsafe(method_family = none)]
377 fn strides(&self) -> Option<Retained<MTLTensorExtents>>;
378
379 /// An array of sizes, in elements, one for each dimension of this tensor.
380 #[unsafe(method(dimensions))]
381 #[unsafe(method_family = none)]
382 fn dimensions(&self) -> Retained<MTLTensorExtents>;
383
384 /// An underlying data format of this tensor.
385 #[unsafe(method(dataType))]
386 #[unsafe(method_family = none)]
387 fn dataType(&self) -> MTLTensorDataType;
388
389 /// A set of contexts in which you can use this tensor.
390 #[unsafe(method(usage))]
391 #[unsafe(method_family = none)]
392 fn usage(&self) -> MTLTensorUsage;
393
394 /// Replaces the contents of a slice of this tensor with data you provide.
395 ///
396 /// - Parameters:
397 /// - sliceOrigin: An array of offsets, in elements, to the first element of the slice that this method writes data to.
398 /// - sliceDimensions: An array of sizes, in elements, of the slice this method writes data to.
399 /// - bytes: A pointer to bytes of data that this method copies into the slice you specify with `sliceOrigin` and `sliceDimensions`.
400 /// - strides: An array of strides, in elements, that describes the layout of the data in `bytes`. You are responsible for ensuring `strides` meets the following requirements:
401 /// - Elements of `strides`are in monotonically non-decreasing order.
402 /// - For any `i` larger than zero, `strides[i]` is greater than or equal to `strides[i-1] * dimensions[i-1]`.
403 ///
404 /// # Safety
405 ///
406 /// `bytes` must be a valid pointer.
407 #[unsafe(method(replaceSliceOrigin:sliceDimensions:withBytes:strides:))]
408 #[unsafe(method_family = none)]
409 unsafe fn replaceSliceOrigin_sliceDimensions_withBytes_strides(
410 &self,
411 slice_origin: &MTLTensorExtents,
412 slice_dimensions: &MTLTensorExtents,
413 bytes: NonNull<c_void>,
414 strides: &MTLTensorExtents,
415 );
416
417 /// Copies the data corresponding to a slice of this tensor into a pointer you provide.
418 ///
419 /// - Parameters:
420 /// - bytes: A pointer to bytes of data that this method copies into the slice you specify with `sliceOrigin` and `sliceDimensions`.
421 /// - strides: An array of strides, in elements, that describes the layout of the data in `bytes`. You are responsible for ensuring `strides` meets the following requirements:
422 /// - Elements of `strides`are in monotonically non-decreasing order.
423 /// - For any `i` larger than zero, `strides[i]` is greater than or equal to `strides[i-1] * dimensions[i-1]`.
424 /// - sliceOrigin: An array of offsets, in elements, to the first element of the slice that this method reads data from.
425 /// - sliceDimensions: An array of sizes, in elements, of the slice this method reads data from.
426 ///
427 /// # Safety
428 ///
429 /// `bytes` must be a valid pointer.
430 #[unsafe(method(getBytes:strides:fromSliceOrigin:sliceDimensions:))]
431 #[unsafe(method_family = none)]
432 unsafe fn getBytes_strides_fromSliceOrigin_sliceDimensions(
433 &self,
434 bytes: NonNull<c_void>,
435 strides: &MTLTensorExtents,
436 slice_origin: &MTLTensorExtents,
437 slice_dimensions: &MTLTensorExtents,
438 );
439 }
440);