metal.commandbuffer source code

1 module metal.commandbuffer;
2 import objc.meta : selector, ObjcExtend;
3 import metal.metal;
4 import metal.rendercommandencoder;
5 import metal.blitcommandencoder;
6 
7 @ObjectiveC final extern(C++):
8 @nogc nothrow:
9 
10 ///Options for reporting errors from a command buffer.
11 enum MTLCommandBufferErrorOption : NSUInteger
12 {
13     ///An option that clears a command buffer’s error options.
14     None = 0,
15     ///An option that instructs a command buffer to save additional details about a GPU runtime error.
16     EncoderExecutionStatus = 1 << 0
17 }
18 
19 ///A configuration that customizes the behavior for a new command buffer.
20 class MTLCommandBufferDescriptor
21 {
22 @nogc nothrow:
23 
24     mixin ObjcExtend!NSObject;
25     @selector("alloc")
26     static MTLCommandBufferDescriptor alloc();
27 
28     @selector("init")
29     MTLCommandBufferDescriptor initialize(); 
30 
31     ///A Boolean value that indicates whether the command buffer the descriptor creates maintains strong references to the resources it uses.
32     @selector("retainedResources")
33     BOOL retainedResources();
34     @selector("setRetainedResources:")
35     BOOL retainedResources(BOOL);
36 
37     ///The reporting configuration that indicates which information the GPU driver stores in a command buffer’s error property.
38     @selector("errorOptions")
39     MTLCommandBufferErrorOption errorOptions();
40 
41     @selector("setErrorOptions:")
42     MTLCommandBufferErrorOption errorOptions(MTLCommandBufferErrorOption);
43 }
44 
45 ///The discrete states for a command buffer that represent its life cycle stages.
46 enum MTLCommandBufferStatus : NSUInteger
47 {
48     ///A command buffer’s initial state, which indicates its command queue isn’t reserving a place for it.
49     NotEnqueued = 0,
50     ///A command buffer’s second state, which indicates its command queue is reserving a place for it.
51     Enqueued = 1,
52     ///A command buffer’s third state, which indicates the command queue is preparing to schedule the command buffer by resolving its dependencies.
53     Committed = 2,
54     ///A command buffer’s fourth state, which indicates the command buffer has its resources ready and is waiting for the GPU to run its commands.
55     Scheduled = 3,
56     ///A command buffer’s successful, final state, which indicates the GPU finished running the command buffer’s commands without any problems.
57     Completed = 4,
58     ///A command buffer’s unsuccessful, final state, which indicates the GPU stopped running the buffer’s commands because of a runtime issue.
59     Error = 5
60 }
61 
62 ///Error codes that indicate why a command buffer is unable to finish its execution.
63 enum MTLCommandBufferError : NSUInteger
64 {
65     ///An error code that represents the absence of any problems.
66     None = 0,
67     ///An error code that indicates the system interrupted and terminated the command buffer because it took more time to execute than the system allows.
68     Timeout = 2,
69     ///An error code that indicates the command buffer generated a page fault the GPU can’t service.
70     PageFault = 3,
71     ///An error code that indicates a process doesn’t have access to a GPU device.
72     NotPermitted = 7,
73     ///An error code that indicates the GPU device doesn’t have sufficient memory to execute a command buffer.
74     OutOfMemory = 8,
75     ///An error code that indicates the command buffer has an invalid reference to resource.
76     InvalidResource = 9,
77     ///An error code that indicates the GPU ran out of one or more of its internal resources that support memoryless render pass attachments.
78     Memoryless = 10,
79     ///An error code that indicates a person physically removed the GPU device before the command buffer finished running.
80     DeviceRemoved = 11,
81     ///An error code that indicates the GPU terminated the command buffer because a kernel function of tile shader used too many stack frames.
82     StackOverflow = 12,
83     ///An error code that indicates the system has revoked the Metal device’s access because it’s responsible for too many timeouts or hangs.
84     AccessRevoked = 4,
85     ///An error code that indicates the Metal framework has an internal problem.
86     ErrorInternal = 1
87 
88 }
89 
90 ///A configuration you create to customize a blit command encoder, which affects the runtime behavior of the blit pass you encode with it.
91 class MTLBlitPassDescriptor
92 {
93 @nogc nothrow:
94 
95     mixin ObjcExtend!NSObject;
96     ///Creates a new blit pass descriptor with a default configuration.
97     @selector("blitPassDescriptor")
98     static MTLBlitPassDescriptor blitPassDescriptor();
99 
100     ///An array of counter sample buffer attachments that you configure for a blit pass.
101 
102 }
103 
104 ///A completion handler signature a GPU device calls when it finishes scheduling a command buffer, or when the GPU finishes running it.
105 alias MTLCommandBufferHandler = extern(C) void function(MTLCommandBuffer);
106 
107 
108 
109 ///Possible error conditions for the command encoder’s commands.
110 enum MTLCommandEncoderErrorState : NSInteger
111 {
112     ///A state that indicates the GPU successfully executed the commands without any errors.
113     Completed = 1, 
114     ///An error state that indicates the GPU didn’t execute the commands.
115     Pending = 3,
116     ///An error state that indicates the GPU failed to fully execute the commands because of an error.
117     Affected = 2,
118     ///An error state that indicates the commands in the command buffer are the cause of an error.
119     Faulted = 4,
120     ///An error state that indicates the command buffer doesn’t know the state of its commands on the GPU.
121     Unknown = 0
122 }
123 
124 
125 ///A container that provides additional information about a runtime failure a GPU encounters as it runs the commands in a command buffer.
126 interface MTLCommandBufferEncoderInfo
127 {
128 @nogc nothrow:
129 
130     ///The name of the encoder that generates the error information
131     @selector("label")
132     NSString label();
133 
134     ///An array of debug signposts that Metal records as the GPU executes the commands of the encoder’s pass.
135     @selector("debugSignposts")
136     NSArray_!NSString debugSignposts();
137 
138     ///The execution status of the command encoder.
139     @selector("errorState")
140     MTLCommandEncoderErrorState errorState();
141 
142 
143 
144 }
145 
146 ///Options for different kinds of function logs.
147 enum MTLFunctionLogType : NSUInteger
148 {
149     ///A message related to usage validation.
150     Validation = 0
151 }
152 
153 
154 ///The source code that logged a debug message.
155 interface MTLFunctionLogDebugLocation
156 {
157 @nogc nothrow:
158 
159     ///The name of the shader function.
160     @selector("functionName")
161     NSString functionName();
162 
163     ///The URL of the file that contains the shader function.
164     @selector("URL")
165     NSURL URL();
166     
167     ///The line that the log message appears on.
168     @selector("line")
169     NSUInteger line();
170     
171     ///The column where the log message appears.
172     @selector("column")
173     NSUInteger column();
174 }
175 
176 
177 ///A log entry a Metal device generates when the it runs a command buffer.
178 interface MTLFunctionLog
179 {
180     ///The type of message that was logged.
181     @selector("type")
182     MTLFunctionLogType type();
183     
184     ///If known, the location of the logging command within a shader source file.
185     @selector("debugLocation")
186     MTLFunctionLogDebugLocation debugLocation();
187     
188     ///The label for the encoder that logged the message.
189     @selector("encoderLabel")
190     NSString encoderLabel();
191     
192     ///When known, the function object corresponding to the logged message.
193     @selector("function")
194     MTLFunction function_();
195 }
196 
197 ///A collection of logged messages, created when a Metal device runs a command buffer.
198 interface MTLLogContainer
199 {
200 @nogc nothrow:
201 
202     mixin ObjcExtend!NSFastEnumeration;
203 }
204 
205 ///A container that stores a sequence of GPU commands that you encode into it.
206 interface MTLCommandBuffer
207 {
208 @nogc nothrow:
209 
210     ///Encodes a command into the command buffer that pauses the GPU from running subsequent passes until the event equals or exceeds a value.
211     @selector("encodeWaitForEvent:value:")
212     void encodeWaitForEvent(MTLEvent event, ulong value);
213 
214     ///Encodes a command into the command buffer that pauses the GPU from running subsequent passes until the event equals or exceeds a value.
215     @selector("encodeSignalEvent:value:")
216     void encodeSignalEvent(MTLEvent event, ulong value);
217 
218     ///Presents a drawable as early as possible.
219     @selector("presentDrawable:")
220     void presentDrawable(MTLDrawable drawable);
221 
222     ///Presents a drawable at a specific time.
223     @selector("presentDrawable:atTime:")
224     void presentDrawable(MTLDrawable drawable, CFTimeInterval presentationTime);
225 
226     ///Presents a drawable after the system presents the previous drawable for an amount of time.
227     @selector("presentDrawable:afterMinimumDuration:")
228     void presentDrawableAfterMinimumDuration(MTLDrawable drawable, CFTimeInterval duration);
229 
230     ///Registers a completion handler the GPU device calls immediately after it schedules the command buffer to run on the GPU.
231     @selector("addScheduleHandler:")
232     void addScheduleHandler(MTLCommandBufferHandler);
233 
234     ///Registers a completion handler the GPU device calls immediately after the GPU finishes running the commands in the command buffer.
235     @selector("addCompletedHandler:")
236     void addCompletedHandler(MTLCommandBufferHandler);
237     
238     ///Reserves the next available place for the command buffer in its command queue.
239     @selector("enqueue")
240     void enqueue();
241 
242     ///Submits the command buffer to run on the GPU.
243     @selector("commit")
244     void commit();
245 
246     ///Synchronously waits for the command queue to schedule the buffer, which can block the current thread’s execution.
247     @selector("waitUntilScheduled")
248     void waitUntilScheduled();
249 
250     ///Synchronously waits for the GPU to finish running the command buffer, which can block the current thread’s execution.
251     @selector("waitUntilCompleted")
252     void waitUntilCompleted();
253 
254     ///The command buffer’s current state.
255     @selector("status")
256     MTLCommandBufferStatus status();
257 
258     @selector("renderCommandEncoderWithDescriptor:")
259     MTLRenderCommandEncoder renderCommandEncoderWithDescriptor(MTLRenderPassDescriptor renderPassDescriptor);
260 
261     ///Creates a block information transfer (blit) encoder.
262     @selector("blitCommandEncoder")
263     MTLBlitCommandEncoder blitCommandEncoder();
264 
265     ///Creates a block information transfer (blit) encoder from a descriptor.
266     @selector("blitCommandEncoderWithDescriptor:")
267     MTLBlitCommandEncoder blitCommandEncoderWithDescriptor(MTLBlitPassDescriptor);
268 
269 
270     ///A string to help identify this object
271     @selector("label")
272     NSString label();
273     @selector("setLabel:")
274     NSString label(NSString);
275 
276 
277     ///The command queue that creates the command buffer.
278     @selector("commandQueue")
279     MTLCommandQueue commandQueue();
280     @selector("setCommandQueue:")
281     MTLCommandQueue commandQueue(MTLCommandQueue);
282 
283     ///Marks the beginning of a debug group and gives it an identifying label, which temporarily replaces the previous group, if applicable.
284     @selector("pushDebugGroup")
285     void pushDebugGroup(NSString);
286 
287 
288     ///Marks the end of a debug group and, if applicable, restores the previous group from a stack.
289     @selector("popDebugGroup")
290     void popDebugGroup();
291 
292 
293     ///A description of an error when the GPU encounters an issue as it runs the command buffer.
294     @selector("error")
295     NSError error();
296     @selector("setError:")
297     NSError error(NSError);
298 
299     /// Settings that determine which information the command buffer records about execution errors, and how it does it.
300     @selector("errorOptions")
301     MTLCommandBufferErrorOption errorOptions();
302     @selector("setErrorOptions:")
303     MTLCommandBufferErrorOption errorOptions(MTLCommandBufferErrorOption);
304 
305     ///The messages the command buffer records as the GPU runs its commands.
306 
307     @selector("logs")
308     MTLLogContainer logs();
309 
310 
311     ///The host time, in seconds, when the CPU begins to schedule the command buffer.
312     @selector("kernelStartTime")
313     CFTimeInterval kernelStartTime();
314 
315     ///The host time, in seconds, when the CPU finishes scheduling the command buffer.
316     @selector("kernelEndTime")
317     CFTimeInterval kernelEndTime();
318 
319     ///The host time, in seconds, when the GPU starts command buffer execution.
320     @selector("GPUStartTime")
321     CFTimeInterval GPUStartTime();
322 
323     ///The host time, in seconds, when the GPU finishes execution of the command buffer.
324     @selector("GPUEndTime")
325     CFTimeInterval GPUEndTime();
326 
327 }