objc2_metal/generated/MTLBinaryArchive.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 "C" {
11 /// [Apple's documentation](https://developer.apple.com/documentation/metal/mtlbinaryarchivedomain?language=objc)
12 pub static MTLBinaryArchiveDomain: &'static NSErrorDomain;
13}
14
15/// [Apple's documentation](https://developer.apple.com/documentation/metal/mtlbinaryarchiveerror?language=objc)
16// NS_ENUM
17#[repr(transparent)]
18#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
19pub struct MTLBinaryArchiveError(pub NSUInteger);
20impl MTLBinaryArchiveError {
21 #[doc(alias = "MTLBinaryArchiveErrorNone")]
22 pub const None: Self = Self(0);
23 #[doc(alias = "MTLBinaryArchiveErrorInvalidFile")]
24 pub const InvalidFile: Self = Self(1);
25 #[doc(alias = "MTLBinaryArchiveErrorUnexpectedElement")]
26 pub const UnexpectedElement: Self = Self(2);
27 #[doc(alias = "MTLBinaryArchiveErrorCompilationFailure")]
28 pub const CompilationFailure: Self = Self(3);
29 #[doc(alias = "MTLBinaryArchiveErrorInternalError")]
30 pub const InternalError: Self = Self(4);
31}
32
33unsafe impl Encode for MTLBinaryArchiveError {
34 const ENCODING: Encoding = NSUInteger::ENCODING;
35}
36
37unsafe impl RefEncode for MTLBinaryArchiveError {
38 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
39}
40
41extern_class!(
42 /// A class used to indicate how an archive should be created
43 ///
44 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtlbinaryarchivedescriptor?language=objc)
45 #[unsafe(super(NSObject))]
46 #[derive(Debug, PartialEq, Eq, Hash)]
47 pub struct MTLBinaryArchiveDescriptor;
48);
49
50extern_conformance!(
51 unsafe impl NSCopying for MTLBinaryArchiveDescriptor {}
52);
53
54unsafe impl CopyingHelper for MTLBinaryArchiveDescriptor {
55 type Result = Self;
56}
57
58extern_conformance!(
59 unsafe impl NSObjectProtocol for MTLBinaryArchiveDescriptor {}
60);
61
62impl MTLBinaryArchiveDescriptor {
63 extern_methods!(
64 /// The file URL from which to open a MTLBinaryArchive, or nil to create an empty MTLBinaryArchive.
65 #[unsafe(method(url))]
66 #[unsafe(method_family = none)]
67 pub fn url(&self) -> Option<Retained<NSURL>>;
68
69 /// Setter for [`url`][Self::url].
70 ///
71 /// This is [copied][objc2_foundation::NSCopying::copy] when set.
72 #[unsafe(method(setUrl:))]
73 #[unsafe(method_family = none)]
74 pub fn setUrl(&self, url: Option<&NSURL>);
75 );
76}
77
78/// Methods declared on superclass `NSObject`.
79impl MTLBinaryArchiveDescriptor {
80 extern_methods!(
81 #[unsafe(method(init))]
82 #[unsafe(method_family = init)]
83 pub fn init(this: Allocated<Self>) -> Retained<Self>;
84
85 #[unsafe(method(new))]
86 #[unsafe(method_family = new)]
87 pub fn new() -> Retained<Self>;
88 );
89}
90
91impl DefaultRetained for MTLBinaryArchiveDescriptor {
92 #[inline]
93 fn default_retained() -> Retained<Self> {
94 Self::new()
95 }
96}
97
98extern_protocol!(
99 /// A container of pipeline state descriptors and their associated compiled code.
100 ///
101 /// A MTLBinaryArchive allows to persist compiled pipeline state objects for a device, which can be used to skip recompilation on a subsequent run of the app.
102 /// One or more archives may be supplied in the descriptor of a pipeline state, allowing the device to attempt to look up compiled code in them before performing compilation.
103 /// If no archives are provided, or no archives contain the requested content, the pipeline state is created by compiling the code as usual.
104 /// Note that software updates of the OS or device drivers may cause the archive to become outdated, causing the lookup to fail and the usual path performing on-demand compilation is taken.
105 /// A MTLBinaryArchive is populated by adding functions from pipeline state descriptors to it, indicating which compiled code should be persisted in the archive.
106 /// Once all desired pipeline state descriptors have been added, use serializeToURL:error: to write the contents for the current device to disk.
107 /// MTLBinaryArchive files generated for multiple different devices can be combined using the "lipo" tool into a single archive, which can then be shipped with the application.
108 /// It is possible to maintain different archive files for different contexts; for example each level in a game may use a different cache object.
109 /// Note: Metal maintains a separate cache of pipeline states on behalf of each app that contains all compiled code; this cache is populated as compilation occurs.
110 /// This cache will automatically accelerate pipeline state creation after a pipeline is created for the first time.
111 /// Use MTLBinaryArchive to augment that cache by accelerating pipeline state creation even on the first run of an app.
112 /// Updating a MTLBinaryArchive at runtime in a shipping app configuration is not recommended; such a scenario requires corruption resiliency, careful storage space management and may cache hard-to-reproduce errors.
113 /// These kind of issues are handled transparently by the Metal maintained cache, therefore we recommend that MTLBinaryArchive is populated during development time and shipped as an asset.
114 ///
115 /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtlbinaryarchive?language=objc)
116 pub unsafe trait MTLBinaryArchive: NSObjectProtocol {
117 /// A string to help identify this object.
118 #[unsafe(method(label))]
119 #[unsafe(method_family = none)]
120 fn label(&self) -> Option<Retained<NSString>>;
121
122 /// Setter for [`label`][Self::label].
123 ///
124 /// This is [copied][objc2_foundation::NSCopying::copy] when set.
125 #[unsafe(method(setLabel:))]
126 #[unsafe(method_family = none)]
127 fn setLabel(&self, label: Option<&NSString>);
128
129 #[cfg(feature = "MTLDevice")]
130 /// The device this resource was created against. This resource can only be used with this device.
131 #[unsafe(method(device))]
132 #[unsafe(method_family = none)]
133 fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>;
134
135 #[cfg(feature = "MTLComputePipeline")]
136 /// Add the function(s) from a compute pipeline state to the archive.
137 ///
138 /// Parameter `descriptor`: The descriptor from which function(s) will be added.
139 ///
140 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain.
141 ///
142 /// Returns: Whether or not the addition succeeded. Functions referenced multiple times are silently accepted.
143 #[unsafe(method(addComputePipelineFunctionsWithDescriptor:error:_))]
144 #[unsafe(method_family = none)]
145 fn addComputePipelineFunctionsWithDescriptor_error(
146 &self,
147 descriptor: &MTLComputePipelineDescriptor,
148 ) -> Result<(), Retained<NSError>>;
149
150 #[cfg(feature = "MTLRenderPipeline")]
151 /// Add the function(s) from a render pipeline state to the archive.
152 ///
153 /// Parameter `descriptor`: The descriptor from which function(s) will be added.
154 ///
155 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain.
156 ///
157 /// Returns: Whether or not the addition succeeded. Functions referenced multiple times are silently accepted.
158 #[unsafe(method(addRenderPipelineFunctionsWithDescriptor:error:_))]
159 #[unsafe(method_family = none)]
160 fn addRenderPipelineFunctionsWithDescriptor_error(
161 &self,
162 descriptor: &MTLRenderPipelineDescriptor,
163 ) -> Result<(), Retained<NSError>>;
164
165 #[cfg(feature = "MTLRenderPipeline")]
166 /// Add the function(s) from a tile render pipeline state to the archive.
167 ///
168 /// Parameter `descriptor`: The descriptor from which function(s) will be added.
169 ///
170 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain.
171 ///
172 /// Returns: Whether or not the addition succeeded. Functions referenced multiple times are silently accepted.
173 #[unsafe(method(addTileRenderPipelineFunctionsWithDescriptor:error:_))]
174 #[unsafe(method_family = none)]
175 fn addTileRenderPipelineFunctionsWithDescriptor_error(
176 &self,
177 descriptor: &MTLTileRenderPipelineDescriptor,
178 ) -> Result<(), Retained<NSError>>;
179
180 #[cfg(feature = "MTLRenderPipeline")]
181 /// Add the function(s) from a mesh render pipeline state to the archive.
182 ///
183 /// Parameter `descriptor`: The descriptor from which function(s) will be added.
184 ///
185 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain.
186 ///
187 /// Returns: Whether or not the addition succeeded. Functions referenced multiple times are silently accepted.
188 #[unsafe(method(addMeshRenderPipelineFunctionsWithDescriptor:error:_))]
189 #[unsafe(method_family = none)]
190 fn addMeshRenderPipelineFunctionsWithDescriptor_error(
191 &self,
192 descriptor: &MTLMeshRenderPipelineDescriptor,
193 ) -> Result<(), Retained<NSError>>;
194
195 #[cfg(feature = "MTLFunctionStitching")]
196 /// Add the function(s) from a stitched library to the archive.
197 ///
198 /// Parameter `descriptor`: The stitched library descriptor from which function(s) will be added.
199 ///
200 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain.
201 ///
202 /// Returns: Whether or not the addition succeeded. Functions referenced multiple times are silently accepted.
203 #[unsafe(method(addLibraryWithDescriptor:error:_))]
204 #[unsafe(method_family = none)]
205 fn addLibraryWithDescriptor_error(
206 &self,
207 descriptor: &MTLStitchedLibraryDescriptor,
208 ) -> Result<(), Retained<NSError>>;
209
210 /// Write the contents of a MTLBinaryArchive to a file.
211 ///
212 /// Persisting the archive to a file allows opening the archive on a subsequent instance of the app, making available the contents without recompiling.
213 ///
214 /// Parameter `url`: The file URL to which to write the file
215 ///
216 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain. Other possible errors can be file access or I/O related.
217 ///
218 /// Returns: Whether or not the writing the file succeeded.
219 #[unsafe(method(serializeToURL:error:_))]
220 #[unsafe(method_family = none)]
221 fn serializeToURL_error(&self, url: &NSURL) -> Result<(), Retained<NSError>>;
222
223 #[cfg(all(feature = "MTLFunctionDescriptor", feature = "MTLLibrary"))]
224 /// Add a `visible` or `intersection` function to the archive.
225 ///
226 /// Parameter `descriptor`: The descriptor from which the function will be added.
227 ///
228 /// Parameter `library`: Library of functions to add the function from.
229 ///
230 /// Parameter `error`: If the function fails, this will be set to describe the failure. This can be (but is not required to be) an error from the MTLBinaryArchiveDomain domain. Other possible errors can be file access or I/O related.
231 ///
232 /// Returns: Whether or not the addition succeeded. Functions referenced multiple times are silently accepted.
233 #[unsafe(method(addFunctionWithDescriptor:library:error:_))]
234 #[unsafe(method_family = none)]
235 fn addFunctionWithDescriptor_library_error(
236 &self,
237 descriptor: &MTLFunctionDescriptor,
238 library: &ProtocolObject<dyn MTLLibrary>,
239 ) -> Result<(), Retained<NSError>>;
240 }
241);