|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /* WIKI CATEGORY: GPU */
|
|
|
23
|
|
|
24 /**
|
|
|
25 * # CategoryGPU
|
|
|
26 *
|
|
|
27 * The GPU API offers a cross-platform way for apps to talk to modern graphics
|
|
|
28 * hardware. It offers both 3D graphics and compute support, in the style of
|
|
|
29 * Metal, Vulkan, and Direct3D 12.
|
|
|
30 *
|
|
|
31 * A basic workflow might be something like this:
|
|
|
32 *
|
|
|
33 * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to
|
|
|
34 * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you
|
|
|
35 * can render offscreen entirely, perhaps for image processing, and not use a
|
|
|
36 * window at all.
|
|
|
37 *
|
|
|
38 * Next, the app prepares static data (things that are created once and used
|
|
|
39 * over and over). For example:
|
|
|
40 *
|
|
|
41 * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader().
|
|
|
42 * - Vertex buffers (arrays of geometry data) and other rendering data: use
|
|
|
43 * SDL_CreateGPUBuffer() and SDL_UploadToGPUBuffer().
|
|
|
44 * - Textures (images): use SDL_CreateGPUTexture() and
|
|
|
45 * SDL_UploadToGPUTexture().
|
|
|
46 * - Samplers (how textures should be read from): use SDL_CreateGPUSampler().
|
|
|
47 * - Render pipelines (precalculated rendering state): use
|
|
|
48 * SDL_CreateGPUGraphicsPipeline()
|
|
|
49 *
|
|
|
50 * To render, the app creates one or more command buffers, with
|
|
|
51 * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering
|
|
|
52 * instructions that will be submitted to the GPU in batch. Complex scenes can
|
|
|
53 * use multiple command buffers, maybe configured across multiple threads in
|
|
|
54 * parallel, as long as they are submitted in the correct order, but many apps
|
|
|
55 * will just need one command buffer per frame.
|
|
|
56 *
|
|
|
57 * Rendering can happen to a texture (what other APIs call a "render target")
|
|
|
58 * or it can happen to the swapchain texture (which is just a special texture
|
|
|
59 * that represents a window's contents). The app can use
|
|
|
60 * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window.
|
|
|
61 *
|
|
|
62 * Rendering actually happens in a Render Pass, which is encoded into a
|
|
|
63 * command buffer. One can encode multiple render passes (or alternate between
|
|
|
64 * render and compute passes) in a single command buffer, but many apps might
|
|
|
65 * simply need a single render pass in a single command buffer. Render Passes
|
|
|
66 * can render to up to four color textures and one depth texture
|
|
|
67 * simultaneously. If the set of textures being rendered to needs to change,
|
|
|
68 * the Render Pass must be ended and a new one must be begun.
|
|
|
69 *
|
|
|
70 * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for
|
|
|
71 * each draw:
|
|
|
72 *
|
|
|
73 * - SDL_BindGPUGraphicsPipeline()
|
|
|
74 * - SDL_SetGPUViewport()
|
|
|
75 * - SDL_BindGPUVertexBuffers()
|
|
|
76 * - SDL_BindGPUVertexSamplers()
|
|
|
77 * - etc
|
|
|
78 *
|
|
|
79 * Then, make the actual draw commands with these states:
|
|
|
80 *
|
|
|
81 * - SDL_DrawGPUPrimitives()
|
|
|
82 * - SDL_DrawGPUPrimitivesIndirect()
|
|
|
83 * - SDL_DrawGPUIndexedPrimitivesIndirect()
|
|
|
84 * - etc
|
|
|
85 *
|
|
|
86 * After all the drawing commands for a pass are complete, the app should call
|
|
|
87 * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is
|
|
|
88 * reset.
|
|
|
89 *
|
|
|
90 * The app can begin new Render Passes and make new draws in the same command
|
|
|
91 * buffer until the entire scene is rendered.
|
|
|
92 *
|
|
|
93 * Once all of the render commands for the scene are complete, the app calls
|
|
|
94 * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing.
|
|
|
95 *
|
|
|
96 * If the app needs to read back data from texture or buffers, the API has an
|
|
|
97 * efficient way of doing this, provided that the app is willing to tolerate
|
|
|
98 * some latency. When the app uses SDL_DownloadFromGPUTexture() or
|
|
|
99 * SDL_DownloadFromGPUBuffer(), submitting the command buffer with
|
|
|
100 * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that
|
|
|
101 * the app can poll or wait on in a thread. Once the fence indicates that the
|
|
|
102 * command buffer is done processing, it is safe to read the downloaded data.
|
|
|
103 * Make sure to call SDL_ReleaseGPUFence() when done with the fence.
|
|
|
104 *
|
|
|
105 * The API also has "compute" support. The app calls SDL_BeginGPUComputePass()
|
|
|
106 * with compute-writeable textures and/or buffers, which can be written to in
|
|
|
107 * a compute shader. Then it sets states it needs for the compute dispatches:
|
|
|
108 *
|
|
|
109 * - SDL_BindGPUComputePipeline()
|
|
|
110 * - SDL_BindGPUComputeStorageBuffers()
|
|
|
111 * - SDL_BindGPUComputeStorageTextures()
|
|
|
112 *
|
|
|
113 * Then, dispatch compute work:
|
|
|
114 *
|
|
|
115 * - SDL_DispatchGPUCompute()
|
|
|
116 *
|
|
|
117 * For advanced users, this opens up powerful GPU-driven workflows.
|
|
|
118 *
|
|
|
119 * Graphics and compute pipelines require the use of shaders, which as
|
|
|
120 * mentioned above are small programs executed on the GPU. Each backend
|
|
|
121 * (Vulkan, Metal, D3D12) requires a different shader format. When the app
|
|
|
122 * creates the GPU device, the app lets the device know which shader formats
|
|
|
123 * the app can provide. It will then select the appropriate backend depending
|
|
|
124 * on the available shader formats and the backends available on the platform.
|
|
|
125 * When creating shaders, the app must provide the correct shader format for
|
|
|
126 * the selected backend. If you would like to learn more about why the API
|
|
|
127 * works this way, there is a detailed
|
|
|
128 * [blog post](https://moonside.games/posts/layers-all-the-way-down/)
|
|
|
129 * explaining this situation.
|
|
|
130 *
|
|
|
131 * It is optimal for apps to pre-compile the shader formats they might use,
|
|
|
132 * but for ease of use SDL provides a separate project,
|
|
|
133 * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross)
|
|
|
134 * , for performing runtime shader cross-compilation. It also has a CLI
|
|
|
135 * interface for offline precompilation as well.
|
|
|
136 *
|
|
|
137 * This is an extremely quick overview that leaves out several important
|
|
|
138 * details. Already, though, one can see that GPU programming can be quite
|
|
|
139 * complex! If you just need simple 2D graphics, the
|
|
|
140 * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender)
|
|
|
141 * is much easier to use but still hardware-accelerated. That said, even for
|
|
|
142 * 2D applications the performance benefits and expressiveness of the GPU API
|
|
|
143 * are significant.
|
|
|
144 *
|
|
|
145 * The GPU API targets a feature set with a wide range of hardware support and
|
|
|
146 * ease of portability. It is designed so that the app won't have to branch
|
|
|
147 * itself by querying feature support. If you need cutting-edge features with
|
|
|
148 * limited hardware support, this API is probably not for you.
|
|
|
149 *
|
|
|
150 * Examples demonstrating proper usage of this API can be found
|
|
|
151 * [here](https://github.com/TheSpydog/SDL_gpu_examples)
|
|
|
152 * .
|
|
|
153 *
|
|
|
154 * ## Performance considerations
|
|
|
155 *
|
|
|
156 * Here are some basic tips for maximizing your rendering performance.
|
|
|
157 *
|
|
|
158 * - Beginning a new render pass is relatively expensive. Use as few render
|
|
|
159 * passes as you can.
|
|
|
160 * - Minimize the amount of state changes. For example, binding a pipeline is
|
|
|
161 * relatively cheap, but doing it hundreds of times when you don't need to
|
|
|
162 * will slow the performance significantly.
|
|
|
163 * - Perform your data uploads as early as possible in the frame.
|
|
|
164 * - Don't churn resources. Creating and releasing resources is expensive.
|
|
|
165 * It's better to create what you need up front and cache it.
|
|
|
166 * - Don't use uniform buffers for large amounts of data (more than a matrix
|
|
|
167 * or so). Use a storage buffer instead.
|
|
|
168 * - Use cycling correctly. There is a detailed explanation of cycling further
|
|
|
169 * below.
|
|
|
170 * - Use culling techniques to minimize pixel writes. The less writing the GPU
|
|
|
171 * has to do the better. Culling can be a very advanced topic but even
|
|
|
172 * simple culling techniques can boost performance significantly.
|
|
|
173 *
|
|
|
174 * In general try to remember the golden rule of performance: doing things is
|
|
|
175 * more expensive than not doing things. Don't Touch The Driver!
|
|
|
176 *
|
|
|
177 * ## FAQ
|
|
|
178 *
|
|
|
179 * **Question: When are you adding more advanced features, like ray tracing or
|
|
|
180 * mesh shaders?**
|
|
|
181 *
|
|
|
182 * Answer: We don't have immediate plans to add more bleeding-edge features,
|
|
|
183 * but we certainly might in the future, when these features prove worthwhile,
|
|
|
184 * and reasonable to implement across several platforms and underlying APIs.
|
|
|
185 * So while these things are not in the "never" category, they are definitely
|
|
|
186 * not "near future" items either.
|
|
|
187 *
|
|
|
188 * **Question: Why is my shader not working?**
|
|
|
189 *
|
|
|
190 * Answer: A common oversight when using shaders is not properly laying out
|
|
|
191 * the shader resources/registers correctly. The GPU API is very strict with
|
|
|
192 * how it wants resources to be laid out and it's difficult for the API to
|
|
|
193 * automatically validate shaders to see if they have a compatible layout. See
|
|
|
194 * the documentation for SDL_CreateGPUShader() and
|
|
|
195 * SDL_CreateGPUComputePipeline() for information on the expected layout.
|
|
|
196 *
|
|
|
197 * Another common issue is not setting the correct number of samplers,
|
|
|
198 * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader
|
|
|
199 * reflection to extract the required information from the shader
|
|
|
200 * automatically instead of manually filling in the struct's values.
|
|
|
201 *
|
|
|
202 * **Question: My application isn't performing very well. Is this the GPU
|
|
|
203 * API's fault?**
|
|
|
204 *
|
|
|
205 * Answer: No. Long answer: The GPU API is a relatively thin layer over the
|
|
|
206 * underlying graphics API. While it's possible that we have done something
|
|
|
207 * inefficiently, it's very unlikely especially if you are relatively
|
|
|
208 * inexperienced with GPU rendering. Please see the performance tips above and
|
|
|
209 * make sure you are following them. Additionally, tools like
|
|
|
210 * [RenderDoc](https://renderdoc.org/)
|
|
|
211 * can be very helpful for diagnosing incorrect behavior and performance
|
|
|
212 * issues.
|
|
|
213 *
|
|
|
214 * ## System Requirements
|
|
|
215 *
|
|
|
216 * ### Vulkan
|
|
|
217 *
|
|
|
218 * SDL driver name: "vulkan" (for use in SDL_CreateGPUDevice() and
|
|
|
219 * SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING)
|
|
|
220 *
|
|
|
221 * Supported on Windows, Linux, Nintendo Switch, and certain Android devices.
|
|
|
222 * Requires Vulkan 1.0 with the following extensions and device features:
|
|
|
223 *
|
|
|
224 * - `VK_KHR_swapchain`
|
|
|
225 * - `VK_KHR_maintenance1`
|
|
|
226 * - `independentBlend`
|
|
|
227 * - `imageCubeArray`
|
|
|
228 * - `depthClamp`
|
|
|
229 * - `shaderClipDistance`
|
|
|
230 * - `drawIndirectFirstInstance`
|
|
|
231 * - `sampleRateShading`
|
|
|
232 *
|
|
|
233 * You can remove some of these requirements to increase compatibility with
|
|
|
234 * Android devices by using these properties when creating the GPU device with
|
|
|
235 * SDL_CreateGPUDeviceWithProperties():
|
|
|
236 *
|
|
|
237 * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN
|
|
|
238 * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN
|
|
|
239 * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN
|
|
|
240 * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN
|
|
|
241 *
|
|
|
242 * ### D3D12
|
|
|
243 *
|
|
|
244 * SDL driver name: "direct3d12"
|
|
|
245 *
|
|
|
246 * Supported on Windows 10 or newer, Xbox One (GDK), and Xbox Series X|S
|
|
|
247 * (GDK). Requires a GPU that supports DirectX 12 Feature Level 11_0 and
|
|
|
248 * Resource Binding Tier 2 or above.
|
|
|
249 *
|
|
|
250 * You can remove the Tier 2 resource binding requirement to support Intel
|
|
|
251 * Haswell and Broadwell GPUs by using this property when creating the GPU
|
|
|
252 * device with SDL_CreateGPUDeviceWithProperties():
|
|
|
253 *
|
|
|
254 * - SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN
|
|
|
255 *
|
|
|
256 * ### Metal
|
|
|
257 *
|
|
|
258 * SDL driver name: "metal"
|
|
|
259 *
|
|
|
260 * Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware requirements vary by
|
|
|
261 * operating system:
|
|
|
262 *
|
|
|
263 * - macOS requires an Apple Silicon or
|
|
|
264 * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc)
|
|
|
265 * GPU
|
|
|
266 * - iOS/tvOS requires an A9 GPU or newer
|
|
|
267 * - iOS Simulator and tvOS Simulator are unsupported
|
|
|
268 *
|
|
|
269 * ## Coordinate System
|
|
|
270 *
|
|
|
271 * The GPU API uses a left-handed coordinate system, following the convention
|
|
|
272 * of D3D12 and Metal. Specifically:
|
|
|
273 *
|
|
|
274 * - **Normalized Device Coordinates:** The lower-left corner has an x,y
|
|
|
275 * coordinate of `(-1.0, -1.0)`. The upper-right corner is `(1.0, 1.0)`. Z
|
|
|
276 * values range from `[0.0, 1.0]` where 0 is the near plane.
|
|
|
277 * - **Viewport Coordinates:** The top-left corner has an x,y coordinate of
|
|
|
278 * `(0, 0)` and extends to the bottom-right corner at `(viewportWidth,
|
|
|
279 * viewportHeight)`. +Y is down.
|
|
|
280 * - **Texture Coordinates:** The top-left corner has an x,y coordinate of
|
|
|
281 * `(0, 0)` and extends to the bottom-right corner at `(1.0, 1.0)`. +Y is
|
|
|
282 * down.
|
|
|
283 *
|
|
|
284 * If the backend driver differs from this convention (e.g. Vulkan, which has
|
|
|
285 * an NDC that assumes +Y is down), SDL will automatically convert the
|
|
|
286 * coordinate system behind the scenes, so you don't need to perform any
|
|
|
287 * coordinate flipping logic in your shaders.
|
|
|
288 *
|
|
|
289 * ## Uniform Data
|
|
|
290 *
|
|
|
291 * Uniforms are for passing data to shaders. The uniform data will be constant
|
|
|
292 * across all executions of the shader.
|
|
|
293 *
|
|
|
294 * There are 4 available uniform slots per shader stage (where the stages are
|
|
|
295 * vertex, fragment, and compute). Uniform data pushed to a slot on a stage
|
|
|
296 * keeps its value throughout the command buffer until you call the relevant
|
|
|
297 * Push function on that slot again.
|
|
|
298 *
|
|
|
299 * For example, you could write your vertex shaders to read a camera matrix
|
|
|
300 * from uniform binding slot 0, push the camera matrix at the start of the
|
|
|
301 * command buffer, and that data will be used for every subsequent draw call.
|
|
|
302 *
|
|
|
303 * It is valid to push uniform data during a render or compute pass.
|
|
|
304 *
|
|
|
305 * Uniforms are best for pushing small amounts of data. If you are pushing
|
|
|
306 * more than a matrix or two per call you should consider using a storage
|
|
|
307 * buffer instead.
|
|
|
308 *
|
|
|
309 * ## A Note On Cycling
|
|
|
310 *
|
|
|
311 * When using a command buffer, operations do not occur immediately - they
|
|
|
312 * occur some time after the command buffer is submitted.
|
|
|
313 *
|
|
|
314 * When a resource is used in a pending or active command buffer, it is
|
|
|
315 * considered to be "bound". When a resource is no longer used in any pending
|
|
|
316 * or active command buffers, it is considered to be "unbound".
|
|
|
317 *
|
|
|
318 * If data resources are bound, it is unspecified when that data will be
|
|
|
319 * unbound unless you acquire a fence when submitting the command buffer and
|
|
|
320 * wait on it. However, this doesn't mean you need to track resource usage
|
|
|
321 * manually.
|
|
|
322 *
|
|
|
323 * All of the functions and structs that involve writing to a resource have a
|
|
|
324 * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all
|
|
|
325 * effectively function as ring buffers on internal resources. When cycle is
|
|
|
326 * true, if the resource is bound, the cycle rotates to the next unbound
|
|
|
327 * internal resource, or if none are available, a new one is created. This
|
|
|
328 * means you don't have to worry about complex state tracking and
|
|
|
329 * synchronization as long as cycling is correctly employed.
|
|
|
330 *
|
|
|
331 * For example: you can call SDL_MapGPUTransferBuffer(), write texture data,
|
|
|
332 * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next
|
|
|
333 * time you write texture data to the transfer buffer, if you set the cycle
|
|
|
334 * param to true, you don't have to worry about overwriting any data that is
|
|
|
335 * not yet uploaded.
|
|
|
336 *
|
|
|
337 * Another example: If you are using a texture in a render pass every frame,
|
|
|
338 * this can cause a data dependency between frames. If you set cycle to true
|
|
|
339 * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency.
|
|
|
340 *
|
|
|
341 * Cycling will never undefine already bound data. When cycling, all data in
|
|
|
342 * the resource is considered to be undefined for subsequent commands until
|
|
|
343 * that data is written again. You must take care not to read undefined data.
|
|
|
344 *
|
|
|
345 * Note that when cycling a texture, the entire texture will be cycled, even
|
|
|
346 * if only part of the texture is used in the call, so you must consider the
|
|
|
347 * entire texture to contain undefined data after cycling.
|
|
|
348 *
|
|
|
349 * You must also take care not to overwrite a section of data that has been
|
|
|
350 * referenced in a command without cycling first. It is OK to overwrite
|
|
|
351 * unreferenced data in a bound resource without cycling, but overwriting a
|
|
|
352 * section of data that has already been referenced will produce unexpected
|
|
|
353 * results.
|
|
|
354 *
|
|
|
355 * ## Debugging
|
|
|
356 *
|
|
|
357 * At some point of your GPU journey, you will probably encounter issues that
|
|
|
358 * are not traceable with regular debugger - for example, your code compiles
|
|
|
359 * but you get an empty screen, or your shader fails in runtime.
|
|
|
360 *
|
|
|
361 * For debugging such cases, there are tools that allow visually inspecting
|
|
|
362 * the whole GPU frame, every drawcall, every bound resource, memory buffers,
|
|
|
363 * etc. They are the following, per platform:
|
|
|
364 *
|
|
|
365 * * For Windows/Linux, use
|
|
|
366 * [RenderDoc](https://renderdoc.org/)
|
|
|
367 * * For MacOS (Metal), use Xcode built-in debugger (Open XCode, go to Debug >
|
|
|
368 * Debug Executable..., select your application, set "GPU Frame Capture" to
|
|
|
369 * "Metal" in scheme "Options" window, run your app, and click the small
|
|
|
370 * Metal icon on the bottom to capture a frame)
|
|
|
371 *
|
|
|
372 * Aside from that, you may want to enable additional debug layers to receive
|
|
|
373 * more detailed error messages, based on your GPU backend:
|
|
|
374 *
|
|
|
375 * * For D3D12, the debug layer is an optional feature that can be installed
|
|
|
376 * via "Windows Settings -> System -> Optional features" and adding the
|
|
|
377 * "Graphics Tools" optional feature.
|
|
|
378 * * For Vulkan, you will need to install Vulkan SDK on Windows, and on Linux,
|
|
|
379 * you usually have some sort of `vulkan-validation-layers` system package
|
|
|
380 * that should be installed.
|
|
|
381 * * For Metal, it should be enough just to run the application from XCode to
|
|
|
382 * receive detailed errors or warnings in the output.
|
|
|
383 *
|
|
|
384 * Don't hesitate to use tools as RenderDoc when encountering runtime issues
|
|
|
385 * or unexpected output on screen, quick GPU frame inspection can usually help
|
|
|
386 * you fix the majority of such problems.
|
|
|
387 */
|
|
|
388
|
|
|
389 #ifndef SDL_gpu_h_
|
|
|
390 #define SDL_gpu_h_
|
|
|
391
|
|
|
392 #include <SDL3/SDL_stdinc.h>
|
|
|
393 #include <SDL3/SDL_pixels.h>
|
|
|
394 #include <SDL3/SDL_properties.h>
|
|
|
395 #include <SDL3/SDL_rect.h>
|
|
|
396 #include <SDL3/SDL_surface.h>
|
|
|
397 #include <SDL3/SDL_video.h>
|
|
|
398
|
|
|
399 #include <SDL3/SDL_begin_code.h>
|
|
|
400 #ifdef __cplusplus
|
|
|
401 extern "C" {
|
|
|
402 #endif /* __cplusplus */
|
|
|
403
|
|
|
404 /* Type Declarations */
|
|
|
405
|
|
|
406 /**
|
|
|
407 * An opaque handle representing the SDL_GPU context.
|
|
|
408 *
|
|
|
409 * \since This struct is available since SDL 3.2.0.
|
|
|
410 */
|
|
|
411 typedef struct SDL_GPUDevice SDL_GPUDevice;
|
|
|
412
|
|
|
413 /**
|
|
|
414 * An opaque handle representing a buffer.
|
|
|
415 *
|
|
|
416 * Used for vertices, indices, indirect draw commands, and general compute
|
|
|
417 * data.
|
|
|
418 *
|
|
|
419 * \since This struct is available since SDL 3.2.0.
|
|
|
420 *
|
|
|
421 * \sa SDL_CreateGPUBuffer
|
|
|
422 * \sa SDL_UploadToGPUBuffer
|
|
|
423 * \sa SDL_DownloadFromGPUBuffer
|
|
|
424 * \sa SDL_CopyGPUBufferToBuffer
|
|
|
425 * \sa SDL_BindGPUVertexBuffers
|
|
|
426 * \sa SDL_BindGPUIndexBuffer
|
|
|
427 * \sa SDL_BindGPUVertexStorageBuffers
|
|
|
428 * \sa SDL_BindGPUFragmentStorageBuffers
|
|
|
429 * \sa SDL_DrawGPUPrimitivesIndirect
|
|
|
430 * \sa SDL_DrawGPUIndexedPrimitivesIndirect
|
|
|
431 * \sa SDL_BindGPUComputeStorageBuffers
|
|
|
432 * \sa SDL_DispatchGPUComputeIndirect
|
|
|
433 * \sa SDL_ReleaseGPUBuffer
|
|
|
434 */
|
|
|
435 typedef struct SDL_GPUBuffer SDL_GPUBuffer;
|
|
|
436
|
|
|
437 /**
|
|
|
438 * An opaque handle representing a transfer buffer.
|
|
|
439 *
|
|
|
440 * Used for transferring data to and from the device.
|
|
|
441 *
|
|
|
442 * \since This struct is available since SDL 3.2.0.
|
|
|
443 *
|
|
|
444 * \sa SDL_CreateGPUTransferBuffer
|
|
|
445 * \sa SDL_MapGPUTransferBuffer
|
|
|
446 * \sa SDL_UnmapGPUTransferBuffer
|
|
|
447 * \sa SDL_UploadToGPUBuffer
|
|
|
448 * \sa SDL_UploadToGPUTexture
|
|
|
449 * \sa SDL_DownloadFromGPUBuffer
|
|
|
450 * \sa SDL_DownloadFromGPUTexture
|
|
|
451 * \sa SDL_ReleaseGPUTransferBuffer
|
|
|
452 */
|
|
|
453 typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer;
|
|
|
454
|
|
|
455 /**
|
|
|
456 * An opaque handle representing a texture.
|
|
|
457 *
|
|
|
458 * \since This struct is available since SDL 3.2.0.
|
|
|
459 *
|
|
|
460 * \sa SDL_CreateGPUTexture
|
|
|
461 * \sa SDL_UploadToGPUTexture
|
|
|
462 * \sa SDL_DownloadFromGPUTexture
|
|
|
463 * \sa SDL_CopyGPUTextureToTexture
|
|
|
464 * \sa SDL_BindGPUVertexSamplers
|
|
|
465 * \sa SDL_BindGPUVertexStorageTextures
|
|
|
466 * \sa SDL_BindGPUFragmentSamplers
|
|
|
467 * \sa SDL_BindGPUFragmentStorageTextures
|
|
|
468 * \sa SDL_BindGPUComputeStorageTextures
|
|
|
469 * \sa SDL_GenerateMipmapsForGPUTexture
|
|
|
470 * \sa SDL_BlitGPUTexture
|
|
|
471 * \sa SDL_ReleaseGPUTexture
|
|
|
472 */
|
|
|
473 typedef struct SDL_GPUTexture SDL_GPUTexture;
|
|
|
474
|
|
|
475 /**
|
|
|
476 * An opaque handle representing a sampler.
|
|
|
477 *
|
|
|
478 * \since This struct is available since SDL 3.2.0.
|
|
|
479 *
|
|
|
480 * \sa SDL_CreateGPUSampler
|
|
|
481 * \sa SDL_BindGPUVertexSamplers
|
|
|
482 * \sa SDL_BindGPUFragmentSamplers
|
|
|
483 * \sa SDL_ReleaseGPUSampler
|
|
|
484 */
|
|
|
485 typedef struct SDL_GPUSampler SDL_GPUSampler;
|
|
|
486
|
|
|
487 /**
|
|
|
488 * An opaque handle representing a compiled shader object.
|
|
|
489 *
|
|
|
490 * \since This struct is available since SDL 3.2.0.
|
|
|
491 *
|
|
|
492 * \sa SDL_CreateGPUShader
|
|
|
493 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
494 * \sa SDL_ReleaseGPUShader
|
|
|
495 */
|
|
|
496 typedef struct SDL_GPUShader SDL_GPUShader;
|
|
|
497
|
|
|
498 /**
|
|
|
499 * An opaque handle representing a compute pipeline.
|
|
|
500 *
|
|
|
501 * Used during compute passes.
|
|
|
502 *
|
|
|
503 * \since This struct is available since SDL 3.2.0.
|
|
|
504 *
|
|
|
505 * \sa SDL_CreateGPUComputePipeline
|
|
|
506 * \sa SDL_BindGPUComputePipeline
|
|
|
507 * \sa SDL_ReleaseGPUComputePipeline
|
|
|
508 */
|
|
|
509 typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline;
|
|
|
510
|
|
|
511 /**
|
|
|
512 * An opaque handle representing a graphics pipeline.
|
|
|
513 *
|
|
|
514 * Used during render passes.
|
|
|
515 *
|
|
|
516 * \since This struct is available since SDL 3.2.0.
|
|
|
517 *
|
|
|
518 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
519 * \sa SDL_BindGPUGraphicsPipeline
|
|
|
520 * \sa SDL_ReleaseGPUGraphicsPipeline
|
|
|
521 */
|
|
|
522 typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline;
|
|
|
523
|
|
|
524 /**
|
|
|
525 * An opaque handle representing a command buffer.
|
|
|
526 *
|
|
|
527 * Most state is managed via command buffers. When setting state using a
|
|
|
528 * command buffer, that state is local to the command buffer.
|
|
|
529 *
|
|
|
530 * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is
|
|
|
531 * called. Once the command buffer is submitted, it is no longer valid to use
|
|
|
532 * it.
|
|
|
533 *
|
|
|
534 * Command buffers are executed in submission order. If you submit command
|
|
|
535 * buffer A and then command buffer B all commands in A will begin executing
|
|
|
536 * before any command in B begins executing.
|
|
|
537 *
|
|
|
538 * In multi-threading scenarios, you should only access a command buffer on
|
|
|
539 * the thread you acquired it from.
|
|
|
540 *
|
|
|
541 * \since This struct is available since SDL 3.2.0.
|
|
|
542 *
|
|
|
543 * \sa SDL_AcquireGPUCommandBuffer
|
|
|
544 * \sa SDL_SubmitGPUCommandBuffer
|
|
|
545 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
546 */
|
|
|
547 typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer;
|
|
|
548
|
|
|
549 /**
|
|
|
550 * An opaque handle representing a render pass.
|
|
|
551 *
|
|
|
552 * This handle is transient and should not be held or referenced after
|
|
|
553 * SDL_EndGPURenderPass is called.
|
|
|
554 *
|
|
|
555 * \since This struct is available since SDL 3.2.0.
|
|
|
556 *
|
|
|
557 * \sa SDL_BeginGPURenderPass
|
|
|
558 * \sa SDL_EndGPURenderPass
|
|
|
559 */
|
|
|
560 typedef struct SDL_GPURenderPass SDL_GPURenderPass;
|
|
|
561
|
|
|
562 /**
|
|
|
563 * An opaque handle representing a compute pass.
|
|
|
564 *
|
|
|
565 * This handle is transient and should not be held or referenced after
|
|
|
566 * SDL_EndGPUComputePass is called.
|
|
|
567 *
|
|
|
568 * \since This struct is available since SDL 3.2.0.
|
|
|
569 *
|
|
|
570 * \sa SDL_BeginGPUComputePass
|
|
|
571 * \sa SDL_EndGPUComputePass
|
|
|
572 */
|
|
|
573 typedef struct SDL_GPUComputePass SDL_GPUComputePass;
|
|
|
574
|
|
|
575 /**
|
|
|
576 * An opaque handle representing a copy pass.
|
|
|
577 *
|
|
|
578 * This handle is transient and should not be held or referenced after
|
|
|
579 * SDL_EndGPUCopyPass is called.
|
|
|
580 *
|
|
|
581 * \since This struct is available since SDL 3.2.0.
|
|
|
582 *
|
|
|
583 * \sa SDL_BeginGPUCopyPass
|
|
|
584 * \sa SDL_EndGPUCopyPass
|
|
|
585 */
|
|
|
586 typedef struct SDL_GPUCopyPass SDL_GPUCopyPass;
|
|
|
587
|
|
|
588 /**
|
|
|
589 * An opaque handle representing a fence.
|
|
|
590 *
|
|
|
591 * \since This struct is available since SDL 3.2.0.
|
|
|
592 *
|
|
|
593 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
594 * \sa SDL_QueryGPUFence
|
|
|
595 * \sa SDL_WaitForGPUFences
|
|
|
596 * \sa SDL_ReleaseGPUFence
|
|
|
597 */
|
|
|
598 typedef struct SDL_GPUFence SDL_GPUFence;
|
|
|
599
|
|
|
600 /**
|
|
|
601 * Specifies the primitive topology of a graphics pipeline.
|
|
|
602 *
|
|
|
603 * If you are using POINTLIST you must include a point size output in the
|
|
|
604 * vertex shader.
|
|
|
605 *
|
|
|
606 * - For HLSL compiling to SPIRV you must decorate a float output with
|
|
|
607 * [[vk::builtin("PointSize")]].
|
|
|
608 * - For GLSL you must set the gl_PointSize builtin.
|
|
|
609 * - For MSL you must include a float output with the [[point_size]]
|
|
|
610 * decorator.
|
|
|
611 *
|
|
|
612 * Note that sized point topology is totally unsupported on D3D12. Any size
|
|
|
613 * other than 1 will be ignored. In general, you should avoid using point
|
|
|
614 * topology for both compatibility and performance reasons. You WILL regret
|
|
|
615 * using it.
|
|
|
616 *
|
|
|
617 * \since This enum is available since SDL 3.2.0.
|
|
|
618 *
|
|
|
619 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
620 */
|
|
|
621 typedef enum SDL_GPUPrimitiveType
|
|
|
622 {
|
|
|
623 SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */
|
|
|
624 SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */
|
|
|
625 SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */
|
|
|
626 SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */
|
|
|
627 SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */
|
|
|
628 } SDL_GPUPrimitiveType;
|
|
|
629
|
|
|
630 /**
|
|
|
631 * Specifies how the contents of a texture attached to a render pass are
|
|
|
632 * treated at the beginning of the render pass.
|
|
|
633 *
|
|
|
634 * \since This enum is available since SDL 3.2.0.
|
|
|
635 *
|
|
|
636 * \sa SDL_BeginGPURenderPass
|
|
|
637 */
|
|
|
638 typedef enum SDL_GPULoadOp
|
|
|
639 {
|
|
|
640 SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */
|
|
|
641 SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */
|
|
|
642 SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */
|
|
|
643 } SDL_GPULoadOp;
|
|
|
644
|
|
|
645 /**
|
|
|
646 * Specifies how the contents of a texture attached to a render pass are
|
|
|
647 * treated at the end of the render pass.
|
|
|
648 *
|
|
|
649 * \since This enum is available since SDL 3.2.0.
|
|
|
650 *
|
|
|
651 * \sa SDL_BeginGPURenderPass
|
|
|
652 */
|
|
|
653 typedef enum SDL_GPUStoreOp
|
|
|
654 {
|
|
|
655 SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */
|
|
|
656 SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */
|
|
|
657 SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */
|
|
|
658 SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */
|
|
|
659 } SDL_GPUStoreOp;
|
|
|
660
|
|
|
661 /**
|
|
|
662 * Specifies the size of elements in an index buffer.
|
|
|
663 *
|
|
|
664 * \since This enum is available since SDL 3.2.0.
|
|
|
665 *
|
|
|
666 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
667 */
|
|
|
668 typedef enum SDL_GPUIndexElementSize
|
|
|
669 {
|
|
|
670 SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */
|
|
|
671 SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */
|
|
|
672 } SDL_GPUIndexElementSize;
|
|
|
673
|
|
|
674 /**
|
|
|
675 * Specifies the pixel format of a texture.
|
|
|
676 *
|
|
|
677 * Texture format support varies depending on driver, hardware, and usage
|
|
|
678 * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if
|
|
|
679 * a format is supported before using it. However, there are a few guaranteed
|
|
|
680 * formats.
|
|
|
681 *
|
|
|
682 * FIXME: Check universal support for 32-bit component formats FIXME: Check
|
|
|
683 * universal support for SIMULTANEOUS_READ_WRITE
|
|
|
684 *
|
|
|
685 * For SAMPLER usage, the following formats are universally supported:
|
|
|
686 *
|
|
|
687 * - R8G8B8A8_UNORM
|
|
|
688 * - B8G8R8A8_UNORM
|
|
|
689 * - R8_UNORM
|
|
|
690 * - R8_SNORM
|
|
|
691 * - R8G8_UNORM
|
|
|
692 * - R8G8_SNORM
|
|
|
693 * - R8G8B8A8_SNORM
|
|
|
694 * - R16_FLOAT
|
|
|
695 * - R16G16_FLOAT
|
|
|
696 * - R16G16B16A16_FLOAT
|
|
|
697 * - R32_FLOAT
|
|
|
698 * - R32G32_FLOAT
|
|
|
699 * - R32G32B32A32_FLOAT
|
|
|
700 * - R11G11B10_UFLOAT
|
|
|
701 * - R8G8B8A8_UNORM_SRGB
|
|
|
702 * - B8G8R8A8_UNORM_SRGB
|
|
|
703 * - D16_UNORM
|
|
|
704 *
|
|
|
705 * For COLOR_TARGET usage, the following formats are universally supported:
|
|
|
706 *
|
|
|
707 * - R8G8B8A8_UNORM
|
|
|
708 * - B8G8R8A8_UNORM
|
|
|
709 * - R8_UNORM
|
|
|
710 * - R16_FLOAT
|
|
|
711 * - R16G16_FLOAT
|
|
|
712 * - R16G16B16A16_FLOAT
|
|
|
713 * - R32_FLOAT
|
|
|
714 * - R32G32_FLOAT
|
|
|
715 * - R32G32B32A32_FLOAT
|
|
|
716 * - R8_UINT
|
|
|
717 * - R8G8_UINT
|
|
|
718 * - R8G8B8A8_UINT
|
|
|
719 * - R16_UINT
|
|
|
720 * - R16G16_UINT
|
|
|
721 * - R16G16B16A16_UINT
|
|
|
722 * - R8_INT
|
|
|
723 * - R8G8_INT
|
|
|
724 * - R8G8B8A8_INT
|
|
|
725 * - R16_INT
|
|
|
726 * - R16G16_INT
|
|
|
727 * - R16G16B16A16_INT
|
|
|
728 * - R8G8B8A8_UNORM_SRGB
|
|
|
729 * - B8G8R8A8_UNORM_SRGB
|
|
|
730 *
|
|
|
731 * For STORAGE usages, the following formats are universally supported:
|
|
|
732 *
|
|
|
733 * - R8G8B8A8_UNORM
|
|
|
734 * - R8G8B8A8_SNORM
|
|
|
735 * - R16G16B16A16_FLOAT
|
|
|
736 * - R32_FLOAT
|
|
|
737 * - R32G32_FLOAT
|
|
|
738 * - R32G32B32A32_FLOAT
|
|
|
739 * - R8G8B8A8_UINT
|
|
|
740 * - R16G16B16A16_UINT
|
|
|
741 * - R8G8B8A8_INT
|
|
|
742 * - R16G16B16A16_INT
|
|
|
743 *
|
|
|
744 * For DEPTH_STENCIL_TARGET usage, the following formats are universally
|
|
|
745 * supported:
|
|
|
746 *
|
|
|
747 * - D16_UNORM
|
|
|
748 * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT
|
|
|
749 * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT
|
|
|
750 *
|
|
|
751 * Unless D16_UNORM is sufficient for your purposes, always check which of
|
|
|
752 * D24/D32 is supported before creating a depth-stencil texture!
|
|
|
753 *
|
|
|
754 * \since This enum is available since SDL 3.2.0.
|
|
|
755 *
|
|
|
756 * \sa SDL_CreateGPUTexture
|
|
|
757 * \sa SDL_GPUTextureSupportsFormat
|
|
|
758 */
|
|
|
759 typedef enum SDL_GPUTextureFormat
|
|
|
760 {
|
|
|
761 SDL_GPU_TEXTUREFORMAT_INVALID,
|
|
|
762
|
|
|
763 /* Unsigned Normalized Float Color Formats */
|
|
|
764 SDL_GPU_TEXTUREFORMAT_A8_UNORM,
|
|
|
765 SDL_GPU_TEXTUREFORMAT_R8_UNORM,
|
|
|
766 SDL_GPU_TEXTUREFORMAT_R8G8_UNORM,
|
|
|
767 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM,
|
|
|
768 SDL_GPU_TEXTUREFORMAT_R16_UNORM,
|
|
|
769 SDL_GPU_TEXTUREFORMAT_R16G16_UNORM,
|
|
|
770 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM,
|
|
|
771 SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM,
|
|
|
772 SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM,
|
|
|
773 SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM,
|
|
|
774 SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM,
|
|
|
775 SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM,
|
|
|
776 /* Compressed Unsigned Normalized Float Color Formats */
|
|
|
777 SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM,
|
|
|
778 SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM,
|
|
|
779 SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM,
|
|
|
780 SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM,
|
|
|
781 SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM,
|
|
|
782 SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM,
|
|
|
783 /* Compressed Signed Float Color Formats */
|
|
|
784 SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT,
|
|
|
785 /* Compressed Unsigned Float Color Formats */
|
|
|
786 SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT,
|
|
|
787 /* Signed Normalized Float Color Formats */
|
|
|
788 SDL_GPU_TEXTUREFORMAT_R8_SNORM,
|
|
|
789 SDL_GPU_TEXTUREFORMAT_R8G8_SNORM,
|
|
|
790 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM,
|
|
|
791 SDL_GPU_TEXTUREFORMAT_R16_SNORM,
|
|
|
792 SDL_GPU_TEXTUREFORMAT_R16G16_SNORM,
|
|
|
793 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM,
|
|
|
794 /* Signed Float Color Formats */
|
|
|
795 SDL_GPU_TEXTUREFORMAT_R16_FLOAT,
|
|
|
796 SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT,
|
|
|
797 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT,
|
|
|
798 SDL_GPU_TEXTUREFORMAT_R32_FLOAT,
|
|
|
799 SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT,
|
|
|
800 SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT,
|
|
|
801 /* Unsigned Float Color Formats */
|
|
|
802 SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT,
|
|
|
803 /* Unsigned Integer Color Formats */
|
|
|
804 SDL_GPU_TEXTUREFORMAT_R8_UINT,
|
|
|
805 SDL_GPU_TEXTUREFORMAT_R8G8_UINT,
|
|
|
806 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UINT,
|
|
|
807 SDL_GPU_TEXTUREFORMAT_R16_UINT,
|
|
|
808 SDL_GPU_TEXTUREFORMAT_R16G16_UINT,
|
|
|
809 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT,
|
|
|
810 SDL_GPU_TEXTUREFORMAT_R32_UINT,
|
|
|
811 SDL_GPU_TEXTUREFORMAT_R32G32_UINT,
|
|
|
812 SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT,
|
|
|
813 /* Signed Integer Color Formats */
|
|
|
814 SDL_GPU_TEXTUREFORMAT_R8_INT,
|
|
|
815 SDL_GPU_TEXTUREFORMAT_R8G8_INT,
|
|
|
816 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT,
|
|
|
817 SDL_GPU_TEXTUREFORMAT_R16_INT,
|
|
|
818 SDL_GPU_TEXTUREFORMAT_R16G16_INT,
|
|
|
819 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT,
|
|
|
820 SDL_GPU_TEXTUREFORMAT_R32_INT,
|
|
|
821 SDL_GPU_TEXTUREFORMAT_R32G32_INT,
|
|
|
822 SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT,
|
|
|
823 /* SRGB Unsigned Normalized Color Formats */
|
|
|
824 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB,
|
|
|
825 SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB,
|
|
|
826 /* Compressed SRGB Unsigned Normalized Color Formats */
|
|
|
827 SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB,
|
|
|
828 SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB,
|
|
|
829 SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB,
|
|
|
830 SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB,
|
|
|
831 /* Depth Formats */
|
|
|
832 SDL_GPU_TEXTUREFORMAT_D16_UNORM,
|
|
|
833 SDL_GPU_TEXTUREFORMAT_D24_UNORM,
|
|
|
834 SDL_GPU_TEXTUREFORMAT_D32_FLOAT,
|
|
|
835 SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT,
|
|
|
836 SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT,
|
|
|
837 /* Compressed ASTC Normalized Float Color Formats*/
|
|
|
838 SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM,
|
|
|
839 SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM,
|
|
|
840 SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM,
|
|
|
841 SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM,
|
|
|
842 SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM,
|
|
|
843 SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM,
|
|
|
844 SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM,
|
|
|
845 SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM,
|
|
|
846 SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM,
|
|
|
847 SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM,
|
|
|
848 SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM,
|
|
|
849 SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM,
|
|
|
850 SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM,
|
|
|
851 SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM,
|
|
|
852 /* Compressed SRGB ASTC Normalized Float Color Formats*/
|
|
|
853 SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB,
|
|
|
854 SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB,
|
|
|
855 SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB,
|
|
|
856 SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB,
|
|
|
857 SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB,
|
|
|
858 SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB,
|
|
|
859 SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB,
|
|
|
860 SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB,
|
|
|
861 SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB,
|
|
|
862 SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB,
|
|
|
863 SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB,
|
|
|
864 SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB,
|
|
|
865 SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB,
|
|
|
866 SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB,
|
|
|
867 /* Compressed ASTC Signed Float Color Formats*/
|
|
|
868 SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT,
|
|
|
869 SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT,
|
|
|
870 SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT,
|
|
|
871 SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT,
|
|
|
872 SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT,
|
|
|
873 SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT,
|
|
|
874 SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT,
|
|
|
875 SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT,
|
|
|
876 SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT,
|
|
|
877 SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT,
|
|
|
878 SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT,
|
|
|
879 SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT,
|
|
|
880 SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT,
|
|
|
881 SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT
|
|
|
882 } SDL_GPUTextureFormat;
|
|
|
883
|
|
|
884 /**
|
|
|
885 * Specifies how a texture is intended to be used by the client.
|
|
|
886 *
|
|
|
887 * A texture must have at least one usage flag. Note that some usage flag
|
|
|
888 * combinations are invalid.
|
|
|
889 *
|
|
|
890 * With regards to compute storage usage, READ | WRITE means that you can have
|
|
|
891 * shader A that only writes into the texture and shader B that only reads
|
|
|
892 * from the texture and bind the same texture to either shader respectively.
|
|
|
893 * SIMULTANEOUS means that you can do reads and writes within the same shader
|
|
|
894 * or compute pass. It also implies that atomic ops can be used, since those
|
|
|
895 * are read-modify-write operations. If you use SIMULTANEOUS, you are
|
|
|
896 * responsible for avoiding data races, as there is no data synchronization
|
|
|
897 * within a compute pass. Note that SIMULTANEOUS usage is only supported by a
|
|
|
898 * limited number of texture formats.
|
|
|
899 *
|
|
|
900 * \since This datatype is available since SDL 3.2.0.
|
|
|
901 *
|
|
|
902 * \sa SDL_CreateGPUTexture
|
|
|
903 */
|
|
|
904 typedef Uint32 SDL_GPUTextureUsageFlags;
|
|
|
905
|
|
|
906 #define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */
|
|
|
907 #define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */
|
|
|
908 #define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */
|
|
|
909 #define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */
|
|
|
910 #define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */
|
|
|
911 #define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */
|
|
|
912 #define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */
|
|
|
913
|
|
|
914 /**
|
|
|
915 * Specifies the type of a texture.
|
|
|
916 *
|
|
|
917 * \since This enum is available since SDL 3.2.0.
|
|
|
918 *
|
|
|
919 * \sa SDL_CreateGPUTexture
|
|
|
920 */
|
|
|
921 typedef enum SDL_GPUTextureType
|
|
|
922 {
|
|
|
923 SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */
|
|
|
924 SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */
|
|
|
925 SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */
|
|
|
926 SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */
|
|
|
927 SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */
|
|
|
928 } SDL_GPUTextureType;
|
|
|
929
|
|
|
930 /**
|
|
|
931 * Specifies the sample count of a texture.
|
|
|
932 *
|
|
|
933 * Used in multisampling. Note that this value only applies when the texture
|
|
|
934 * is used as a render target.
|
|
|
935 *
|
|
|
936 * \since This enum is available since SDL 3.2.0.
|
|
|
937 *
|
|
|
938 * \sa SDL_CreateGPUTexture
|
|
|
939 * \sa SDL_GPUTextureSupportsSampleCount
|
|
|
940 */
|
|
|
941 typedef enum SDL_GPUSampleCount
|
|
|
942 {
|
|
|
943 SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */
|
|
|
944 SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */
|
|
|
945 SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */
|
|
|
946 SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */
|
|
|
947 } SDL_GPUSampleCount;
|
|
|
948
|
|
|
949
|
|
|
950 /**
|
|
|
951 * Specifies the face of a cube map.
|
|
|
952 *
|
|
|
953 * Can be passed in as the layer field in texture-related structs.
|
|
|
954 *
|
|
|
955 * \since This enum is available since SDL 3.2.0.
|
|
|
956 */
|
|
|
957 typedef enum SDL_GPUCubeMapFace
|
|
|
958 {
|
|
|
959 SDL_GPU_CUBEMAPFACE_POSITIVEX,
|
|
|
960 SDL_GPU_CUBEMAPFACE_NEGATIVEX,
|
|
|
961 SDL_GPU_CUBEMAPFACE_POSITIVEY,
|
|
|
962 SDL_GPU_CUBEMAPFACE_NEGATIVEY,
|
|
|
963 SDL_GPU_CUBEMAPFACE_POSITIVEZ,
|
|
|
964 SDL_GPU_CUBEMAPFACE_NEGATIVEZ
|
|
|
965 } SDL_GPUCubeMapFace;
|
|
|
966
|
|
|
967 /**
|
|
|
968 * Specifies how a buffer is intended to be used by the client.
|
|
|
969 *
|
|
|
970 * A buffer must have at least one usage flag. Note that some usage flag
|
|
|
971 * combinations are invalid.
|
|
|
972 *
|
|
|
973 * Unlike textures, READ | WRITE can be used for simultaneous read-write
|
|
|
974 * usage. The same data synchronization concerns as textures apply.
|
|
|
975 *
|
|
|
976 * If you use a STORAGE flag, the data in the buffer must respect std140
|
|
|
977 * layout conventions. In practical terms this means you must ensure that vec3
|
|
|
978 * and vec4 fields are 16-byte aligned.
|
|
|
979 *
|
|
|
980 * \since This datatype is available since SDL 3.2.0.
|
|
|
981 *
|
|
|
982 * \sa SDL_CreateGPUBuffer
|
|
|
983 */
|
|
|
984 typedef Uint32 SDL_GPUBufferUsageFlags;
|
|
|
985
|
|
|
986 #define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */
|
|
|
987 #define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */
|
|
|
988 #define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */
|
|
|
989 #define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */
|
|
|
990 #define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */
|
|
|
991 #define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */
|
|
|
992
|
|
|
993 /**
|
|
|
994 * Specifies how a transfer buffer is intended to be used by the client.
|
|
|
995 *
|
|
|
996 * Note that mapping and copying FROM an upload transfer buffer or TO a
|
|
|
997 * download transfer buffer is undefined behavior.
|
|
|
998 *
|
|
|
999 * \since This enum is available since SDL 3.2.0.
|
|
|
1000 *
|
|
|
1001 * \sa SDL_CreateGPUTransferBuffer
|
|
|
1002 */
|
|
|
1003 typedef enum SDL_GPUTransferBufferUsage
|
|
|
1004 {
|
|
|
1005 SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD,
|
|
|
1006 SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD
|
|
|
1007 } SDL_GPUTransferBufferUsage;
|
|
|
1008
|
|
|
1009 /**
|
|
|
1010 * Specifies which stage a shader program corresponds to.
|
|
|
1011 *
|
|
|
1012 * \since This enum is available since SDL 3.2.0.
|
|
|
1013 *
|
|
|
1014 * \sa SDL_CreateGPUShader
|
|
|
1015 */
|
|
|
1016 typedef enum SDL_GPUShaderStage
|
|
|
1017 {
|
|
|
1018 SDL_GPU_SHADERSTAGE_VERTEX,
|
|
|
1019 SDL_GPU_SHADERSTAGE_FRAGMENT
|
|
|
1020 } SDL_GPUShaderStage;
|
|
|
1021
|
|
|
1022 /**
|
|
|
1023 * Specifies the format of shader code.
|
|
|
1024 *
|
|
|
1025 * Each format corresponds to a specific backend that accepts it.
|
|
|
1026 *
|
|
|
1027 * \since This datatype is available since SDL 3.2.0.
|
|
|
1028 *
|
|
|
1029 * \sa SDL_CreateGPUShader
|
|
|
1030 */
|
|
|
1031 typedef Uint32 SDL_GPUShaderFormat;
|
|
|
1032
|
|
|
1033 #define SDL_GPU_SHADERFORMAT_INVALID 0
|
|
|
1034 #define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */
|
|
|
1035 #define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */
|
|
|
1036 #define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */
|
|
|
1037 #define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */
|
|
|
1038 #define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */
|
|
|
1039 #define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */
|
|
|
1040
|
|
|
1041 /**
|
|
|
1042 * Specifies the format of a vertex attribute.
|
|
|
1043 *
|
|
|
1044 * \since This enum is available since SDL 3.2.0.
|
|
|
1045 *
|
|
|
1046 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1047 */
|
|
|
1048 typedef enum SDL_GPUVertexElementFormat
|
|
|
1049 {
|
|
|
1050 SDL_GPU_VERTEXELEMENTFORMAT_INVALID,
|
|
|
1051
|
|
|
1052 /* 32-bit Signed Integers */
|
|
|
1053 SDL_GPU_VERTEXELEMENTFORMAT_INT,
|
|
|
1054 SDL_GPU_VERTEXELEMENTFORMAT_INT2,
|
|
|
1055 SDL_GPU_VERTEXELEMENTFORMAT_INT3,
|
|
|
1056 SDL_GPU_VERTEXELEMENTFORMAT_INT4,
|
|
|
1057
|
|
|
1058 /* 32-bit Unsigned Integers */
|
|
|
1059 SDL_GPU_VERTEXELEMENTFORMAT_UINT,
|
|
|
1060 SDL_GPU_VERTEXELEMENTFORMAT_UINT2,
|
|
|
1061 SDL_GPU_VERTEXELEMENTFORMAT_UINT3,
|
|
|
1062 SDL_GPU_VERTEXELEMENTFORMAT_UINT4,
|
|
|
1063
|
|
|
1064 /* 32-bit Floats */
|
|
|
1065 SDL_GPU_VERTEXELEMENTFORMAT_FLOAT,
|
|
|
1066 SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2,
|
|
|
1067 SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3,
|
|
|
1068 SDL_GPU_VERTEXELEMENTFORMAT_FLOAT4,
|
|
|
1069
|
|
|
1070 /* 8-bit Signed Integers */
|
|
|
1071 SDL_GPU_VERTEXELEMENTFORMAT_BYTE2,
|
|
|
1072 SDL_GPU_VERTEXELEMENTFORMAT_BYTE4,
|
|
|
1073
|
|
|
1074 /* 8-bit Unsigned Integers */
|
|
|
1075 SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2,
|
|
|
1076 SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4,
|
|
|
1077
|
|
|
1078 /* 8-bit Signed Normalized */
|
|
|
1079 SDL_GPU_VERTEXELEMENTFORMAT_BYTE2_NORM,
|
|
|
1080 SDL_GPU_VERTEXELEMENTFORMAT_BYTE4_NORM,
|
|
|
1081
|
|
|
1082 /* 8-bit Unsigned Normalized */
|
|
|
1083 SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2_NORM,
|
|
|
1084 SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM,
|
|
|
1085
|
|
|
1086 /* 16-bit Signed Integers */
|
|
|
1087 SDL_GPU_VERTEXELEMENTFORMAT_SHORT2,
|
|
|
1088 SDL_GPU_VERTEXELEMENTFORMAT_SHORT4,
|
|
|
1089
|
|
|
1090 /* 16-bit Unsigned Integers */
|
|
|
1091 SDL_GPU_VERTEXELEMENTFORMAT_USHORT2,
|
|
|
1092 SDL_GPU_VERTEXELEMENTFORMAT_USHORT4,
|
|
|
1093
|
|
|
1094 /* 16-bit Signed Normalized */
|
|
|
1095 SDL_GPU_VERTEXELEMENTFORMAT_SHORT2_NORM,
|
|
|
1096 SDL_GPU_VERTEXELEMENTFORMAT_SHORT4_NORM,
|
|
|
1097
|
|
|
1098 /* 16-bit Unsigned Normalized */
|
|
|
1099 SDL_GPU_VERTEXELEMENTFORMAT_USHORT2_NORM,
|
|
|
1100 SDL_GPU_VERTEXELEMENTFORMAT_USHORT4_NORM,
|
|
|
1101
|
|
|
1102 /* 16-bit Floats */
|
|
|
1103 SDL_GPU_VERTEXELEMENTFORMAT_HALF2,
|
|
|
1104 SDL_GPU_VERTEXELEMENTFORMAT_HALF4
|
|
|
1105 } SDL_GPUVertexElementFormat;
|
|
|
1106
|
|
|
1107 /**
|
|
|
1108 * Specifies the rate at which vertex attributes are pulled from buffers.
|
|
|
1109 *
|
|
|
1110 * \since This enum is available since SDL 3.2.0.
|
|
|
1111 *
|
|
|
1112 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1113 */
|
|
|
1114 typedef enum SDL_GPUVertexInputRate
|
|
|
1115 {
|
|
|
1116 SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */
|
|
|
1117 SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */
|
|
|
1118 } SDL_GPUVertexInputRate;
|
|
|
1119
|
|
|
1120 /**
|
|
|
1121 * Specifies the fill mode of the graphics pipeline.
|
|
|
1122 *
|
|
|
1123 * \since This enum is available since SDL 3.2.0.
|
|
|
1124 *
|
|
|
1125 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1126 */
|
|
|
1127 typedef enum SDL_GPUFillMode
|
|
|
1128 {
|
|
|
1129 SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */
|
|
|
1130 SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */
|
|
|
1131 } SDL_GPUFillMode;
|
|
|
1132
|
|
|
1133 /**
|
|
|
1134 * Specifies the facing direction in which triangle faces will be culled.
|
|
|
1135 *
|
|
|
1136 * \since This enum is available since SDL 3.2.0.
|
|
|
1137 *
|
|
|
1138 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1139 */
|
|
|
1140 typedef enum SDL_GPUCullMode
|
|
|
1141 {
|
|
|
1142 SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */
|
|
|
1143 SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */
|
|
|
1144 SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */
|
|
|
1145 } SDL_GPUCullMode;
|
|
|
1146
|
|
|
1147 /**
|
|
|
1148 * Specifies the vertex winding that will cause a triangle to be determined to
|
|
|
1149 * be front-facing.
|
|
|
1150 *
|
|
|
1151 * \since This enum is available since SDL 3.2.0.
|
|
|
1152 *
|
|
|
1153 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1154 */
|
|
|
1155 typedef enum SDL_GPUFrontFace
|
|
|
1156 {
|
|
|
1157 SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */
|
|
|
1158 SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */
|
|
|
1159 } SDL_GPUFrontFace;
|
|
|
1160
|
|
|
1161 /**
|
|
|
1162 * Specifies a comparison operator for depth, stencil and sampler operations.
|
|
|
1163 *
|
|
|
1164 * \since This enum is available since SDL 3.2.0.
|
|
|
1165 *
|
|
|
1166 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1167 */
|
|
|
1168 typedef enum SDL_GPUCompareOp
|
|
|
1169 {
|
|
|
1170 SDL_GPU_COMPAREOP_INVALID,
|
|
|
1171 SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */
|
|
|
1172 SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */
|
|
|
1173 SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */
|
|
|
1174 SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */
|
|
|
1175 SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */
|
|
|
1176 SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */
|
|
|
1177 SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evaluates reference >= test. */
|
|
|
1178 SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */
|
|
|
1179 } SDL_GPUCompareOp;
|
|
|
1180
|
|
|
1181 /**
|
|
|
1182 * Specifies what happens to a stored stencil value if stencil tests fail or
|
|
|
1183 * pass.
|
|
|
1184 *
|
|
|
1185 * \since This enum is available since SDL 3.2.0.
|
|
|
1186 *
|
|
|
1187 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1188 */
|
|
|
1189 typedef enum SDL_GPUStencilOp
|
|
|
1190 {
|
|
|
1191 SDL_GPU_STENCILOP_INVALID,
|
|
|
1192 SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */
|
|
|
1193 SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */
|
|
|
1194 SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */
|
|
|
1195 SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */
|
|
|
1196 SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */
|
|
|
1197 SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */
|
|
|
1198 SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */
|
|
|
1199 SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */
|
|
|
1200 } SDL_GPUStencilOp;
|
|
|
1201
|
|
|
1202 /**
|
|
|
1203 * Specifies the operator to be used when pixels in a render target are
|
|
|
1204 * blended with existing pixels in the texture.
|
|
|
1205 *
|
|
|
1206 * The source color is the value written by the fragment shader. The
|
|
|
1207 * destination color is the value currently existing in the texture.
|
|
|
1208 *
|
|
|
1209 * \since This enum is available since SDL 3.2.0.
|
|
|
1210 *
|
|
|
1211 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1212 */
|
|
|
1213 typedef enum SDL_GPUBlendOp
|
|
|
1214 {
|
|
|
1215 SDL_GPU_BLENDOP_INVALID,
|
|
|
1216 SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */
|
|
|
1217 SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */
|
|
|
1218 SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */
|
|
|
1219 SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */
|
|
|
1220 SDL_GPU_BLENDOP_MAX /**< max(source, destination) */
|
|
|
1221 } SDL_GPUBlendOp;
|
|
|
1222
|
|
|
1223 /**
|
|
|
1224 * Specifies a blending factor to be used when pixels in a render target are
|
|
|
1225 * blended with existing pixels in the texture.
|
|
|
1226 *
|
|
|
1227 * The source color is the value written by the fragment shader. The
|
|
|
1228 * destination color is the value currently existing in the texture.
|
|
|
1229 *
|
|
|
1230 * \since This enum is available since SDL 3.2.0.
|
|
|
1231 *
|
|
|
1232 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1233 */
|
|
|
1234 typedef enum SDL_GPUBlendFactor
|
|
|
1235 {
|
|
|
1236 SDL_GPU_BLENDFACTOR_INVALID,
|
|
|
1237 SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */
|
|
|
1238 SDL_GPU_BLENDFACTOR_ONE, /**< 1 */
|
|
|
1239 SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */
|
|
|
1240 SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */
|
|
|
1241 SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */
|
|
|
1242 SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */
|
|
|
1243 SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */
|
|
|
1244 SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */
|
|
|
1245 SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */
|
|
|
1246 SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */
|
|
|
1247 SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */
|
|
|
1248 SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */
|
|
|
1249 SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */
|
|
|
1250 } SDL_GPUBlendFactor;
|
|
|
1251
|
|
|
1252 /**
|
|
|
1253 * Specifies which color components are written in a graphics pipeline.
|
|
|
1254 *
|
|
|
1255 * \since This datatype is available since SDL 3.2.0.
|
|
|
1256 *
|
|
|
1257 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1258 */
|
|
|
1259 typedef Uint8 SDL_GPUColorComponentFlags;
|
|
|
1260
|
|
|
1261 #define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */
|
|
|
1262 #define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */
|
|
|
1263 #define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */
|
|
|
1264 #define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */
|
|
|
1265
|
|
|
1266 /**
|
|
|
1267 * Specifies a filter operation used by a sampler.
|
|
|
1268 *
|
|
|
1269 * \since This enum is available since SDL 3.2.0.
|
|
|
1270 *
|
|
|
1271 * \sa SDL_CreateGPUSampler
|
|
|
1272 */
|
|
|
1273 typedef enum SDL_GPUFilter
|
|
|
1274 {
|
|
|
1275 SDL_GPU_FILTER_NEAREST, /**< Point filtering. */
|
|
|
1276 SDL_GPU_FILTER_LINEAR /**< Linear filtering. */
|
|
|
1277 } SDL_GPUFilter;
|
|
|
1278
|
|
|
1279 /**
|
|
|
1280 * Specifies a mipmap mode used by a sampler.
|
|
|
1281 *
|
|
|
1282 * \since This enum is available since SDL 3.2.0.
|
|
|
1283 *
|
|
|
1284 * \sa SDL_CreateGPUSampler
|
|
|
1285 */
|
|
|
1286 typedef enum SDL_GPUSamplerMipmapMode
|
|
|
1287 {
|
|
|
1288 SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */
|
|
|
1289 SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */
|
|
|
1290 } SDL_GPUSamplerMipmapMode;
|
|
|
1291
|
|
|
1292 /**
|
|
|
1293 * Specifies behavior of texture sampling when the coordinates exceed the 0-1
|
|
|
1294 * range.
|
|
|
1295 *
|
|
|
1296 * \since This enum is available since SDL 3.2.0.
|
|
|
1297 *
|
|
|
1298 * \sa SDL_CreateGPUSampler
|
|
|
1299 */
|
|
|
1300 typedef enum SDL_GPUSamplerAddressMode
|
|
|
1301 {
|
|
|
1302 SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */
|
|
|
1303 SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */
|
|
|
1304 SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */
|
|
|
1305 } SDL_GPUSamplerAddressMode;
|
|
|
1306
|
|
|
1307 /**
|
|
|
1308 * Specifies the timing that will be used to present swapchain textures to the
|
|
|
1309 * OS.
|
|
|
1310 *
|
|
|
1311 * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be
|
|
|
1312 * supported on certain systems.
|
|
|
1313 *
|
|
|
1314 * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming
|
|
|
1315 * the window if you wish to change the present mode to IMMEDIATE or MAILBOX.
|
|
|
1316 *
|
|
|
1317 * - VSYNC: Waits for vblank before presenting. No tearing is possible. If
|
|
|
1318 * there is a pending image to present, the new image is enqueued for
|
|
|
1319 * presentation. Disallows tearing at the cost of visual latency.
|
|
|
1320 * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may
|
|
|
1321 * occur.
|
|
|
1322 * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If
|
|
|
1323 * there is a pending image to present, the pending image is replaced by the
|
|
|
1324 * new image. Similar to VSYNC, but with reduced visual latency.
|
|
|
1325 *
|
|
|
1326 * \since This enum is available since SDL 3.2.0.
|
|
|
1327 *
|
|
|
1328 * \sa SDL_SetGPUSwapchainParameters
|
|
|
1329 * \sa SDL_WindowSupportsGPUPresentMode
|
|
|
1330 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
1331 */
|
|
|
1332 typedef enum SDL_GPUPresentMode
|
|
|
1333 {
|
|
|
1334 SDL_GPU_PRESENTMODE_VSYNC,
|
|
|
1335 SDL_GPU_PRESENTMODE_IMMEDIATE,
|
|
|
1336 SDL_GPU_PRESENTMODE_MAILBOX
|
|
|
1337 } SDL_GPUPresentMode;
|
|
|
1338
|
|
|
1339 /**
|
|
|
1340 * Specifies the texture format and colorspace of the swapchain textures.
|
|
|
1341 *
|
|
|
1342 * SDR will always be supported. Other compositions may not be supported on
|
|
|
1343 * certain systems.
|
|
|
1344 *
|
|
|
1345 * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after
|
|
|
1346 * claiming the window if you wish to change the swapchain composition from
|
|
|
1347 * SDR.
|
|
|
1348 *
|
|
|
1349 * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding.
|
|
|
1350 * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are
|
|
|
1351 * stored in memory in sRGB encoding but accessed in shaders in "linear
|
|
|
1352 * sRGB" encoding which is sRGB but with a linear transfer function.
|
|
|
1353 * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in
|
|
|
1354 * extended linear sRGB encoding and permits values outside of the [0, 1]
|
|
|
1355 * range.
|
|
|
1356 * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in
|
|
|
1357 * BT.2020 ST2084 (PQ) encoding.
|
|
|
1358 *
|
|
|
1359 * \since This enum is available since SDL 3.2.0.
|
|
|
1360 *
|
|
|
1361 * \sa SDL_SetGPUSwapchainParameters
|
|
|
1362 * \sa SDL_WindowSupportsGPUSwapchainComposition
|
|
|
1363 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
1364 */
|
|
|
1365 typedef enum SDL_GPUSwapchainComposition
|
|
|
1366 {
|
|
|
1367 SDL_GPU_SWAPCHAINCOMPOSITION_SDR,
|
|
|
1368 SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR,
|
|
|
1369 SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR,
|
|
|
1370 SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084
|
|
|
1371 } SDL_GPUSwapchainComposition;
|
|
|
1372
|
|
|
1373 /* Structures */
|
|
|
1374
|
|
|
1375 /**
|
|
|
1376 * A structure specifying a viewport.
|
|
|
1377 *
|
|
|
1378 * \since This struct is available since SDL 3.2.0.
|
|
|
1379 *
|
|
|
1380 * \sa SDL_SetGPUViewport
|
|
|
1381 */
|
|
|
1382 typedef struct SDL_GPUViewport
|
|
|
1383 {
|
|
|
1384 float x; /**< The left offset of the viewport. */
|
|
|
1385 float y; /**< The top offset of the viewport. */
|
|
|
1386 float w; /**< The width of the viewport. */
|
|
|
1387 float h; /**< The height of the viewport. */
|
|
|
1388 float min_depth; /**< The minimum depth of the viewport. */
|
|
|
1389 float max_depth; /**< The maximum depth of the viewport. */
|
|
|
1390 } SDL_GPUViewport;
|
|
|
1391
|
|
|
1392 /**
|
|
|
1393 * A structure specifying parameters related to transferring data to or from a
|
|
|
1394 * texture.
|
|
|
1395 *
|
|
|
1396 * If either of `pixels_per_row` or `rows_per_layer` is zero, then width and
|
|
|
1397 * height of passed SDL_GPUTextureRegion to SDL_UploadToGPUTexture or
|
|
|
1398 * SDL_DownloadFromGPUTexture are used as default values respectively and data
|
|
|
1399 * is considered to be tightly packed.
|
|
|
1400 *
|
|
|
1401 * **WARNING**: Direct3D 12 requires texture data row pitch to be 256 byte
|
|
|
1402 * aligned, and offsets to be aligned to 512 bytes. If they are not, SDL will
|
|
|
1403 * make a temporary copy of the data that is properly aligned, but this adds
|
|
|
1404 * overhead to the transfer process. Apps can avoid this by aligning their
|
|
|
1405 * data appropriately, or using a different GPU backend than Direct3D 12.
|
|
|
1406 *
|
|
|
1407 * \since This struct is available since SDL 3.2.0.
|
|
|
1408 *
|
|
|
1409 * \sa SDL_UploadToGPUTexture
|
|
|
1410 * \sa SDL_DownloadFromGPUTexture
|
|
|
1411 */
|
|
|
1412 typedef struct SDL_GPUTextureTransferInfo
|
|
|
1413 {
|
|
|
1414 SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */
|
|
|
1415 Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */
|
|
|
1416 Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */
|
|
|
1417 Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */
|
|
|
1418 } SDL_GPUTextureTransferInfo;
|
|
|
1419
|
|
|
1420 /**
|
|
|
1421 * A structure specifying a location in a transfer buffer.
|
|
|
1422 *
|
|
|
1423 * Used when transferring buffer data to or from a transfer buffer.
|
|
|
1424 *
|
|
|
1425 * \since This struct is available since SDL 3.2.0.
|
|
|
1426 *
|
|
|
1427 * \sa SDL_UploadToGPUBuffer
|
|
|
1428 * \sa SDL_DownloadFromGPUBuffer
|
|
|
1429 */
|
|
|
1430 typedef struct SDL_GPUTransferBufferLocation
|
|
|
1431 {
|
|
|
1432 SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */
|
|
|
1433 Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */
|
|
|
1434 } SDL_GPUTransferBufferLocation;
|
|
|
1435
|
|
|
1436 /**
|
|
|
1437 * A structure specifying a location in a texture.
|
|
|
1438 *
|
|
|
1439 * Used when copying data from one texture to another.
|
|
|
1440 *
|
|
|
1441 * \since This struct is available since SDL 3.2.0.
|
|
|
1442 *
|
|
|
1443 * \sa SDL_CopyGPUTextureToTexture
|
|
|
1444 */
|
|
|
1445 typedef struct SDL_GPUTextureLocation
|
|
|
1446 {
|
|
|
1447 SDL_GPUTexture *texture; /**< The texture used in the copy operation. */
|
|
|
1448 Uint32 mip_level; /**< The mip level index of the location. */
|
|
|
1449 Uint32 layer; /**< The layer index of the location. */
|
|
|
1450 Uint32 x; /**< The left offset of the location. */
|
|
|
1451 Uint32 y; /**< The top offset of the location. */
|
|
|
1452 Uint32 z; /**< The front offset of the location. */
|
|
|
1453 } SDL_GPUTextureLocation;
|
|
|
1454
|
|
|
1455 /**
|
|
|
1456 * A structure specifying a region of a texture.
|
|
|
1457 *
|
|
|
1458 * Used when transferring data to or from a texture.
|
|
|
1459 *
|
|
|
1460 * \since This struct is available since SDL 3.2.0.
|
|
|
1461 *
|
|
|
1462 * \sa SDL_UploadToGPUTexture
|
|
|
1463 * \sa SDL_DownloadFromGPUTexture
|
|
|
1464 * \sa SDL_CreateGPUTexture
|
|
|
1465 */
|
|
|
1466 typedef struct SDL_GPUTextureRegion
|
|
|
1467 {
|
|
|
1468 SDL_GPUTexture *texture; /**< The texture used in the copy operation. */
|
|
|
1469 Uint32 mip_level; /**< The mip level index to transfer. */
|
|
|
1470 Uint32 layer; /**< The layer index to transfer. */
|
|
|
1471 Uint32 x; /**< The left offset of the region. */
|
|
|
1472 Uint32 y; /**< The top offset of the region. */
|
|
|
1473 Uint32 z; /**< The front offset of the region. */
|
|
|
1474 Uint32 w; /**< The width of the region. */
|
|
|
1475 Uint32 h; /**< The height of the region. */
|
|
|
1476 Uint32 d; /**< The depth of the region. */
|
|
|
1477 } SDL_GPUTextureRegion;
|
|
|
1478
|
|
|
1479 /**
|
|
|
1480 * A structure specifying a region of a texture used in the blit operation.
|
|
|
1481 *
|
|
|
1482 * \since This struct is available since SDL 3.2.0.
|
|
|
1483 *
|
|
|
1484 * \sa SDL_BlitGPUTexture
|
|
|
1485 */
|
|
|
1486 typedef struct SDL_GPUBlitRegion
|
|
|
1487 {
|
|
|
1488 SDL_GPUTexture *texture; /**< The texture. */
|
|
|
1489 Uint32 mip_level; /**< The mip level index of the region. */
|
|
|
1490 Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */
|
|
|
1491 Uint32 x; /**< The left offset of the region. */
|
|
|
1492 Uint32 y; /**< The top offset of the region. */
|
|
|
1493 Uint32 w; /**< The width of the region. */
|
|
|
1494 Uint32 h; /**< The height of the region. */
|
|
|
1495 } SDL_GPUBlitRegion;
|
|
|
1496
|
|
|
1497 /**
|
|
|
1498 * A structure specifying a location in a buffer.
|
|
|
1499 *
|
|
|
1500 * Used when copying data between buffers.
|
|
|
1501 *
|
|
|
1502 * \since This struct is available since SDL 3.2.0.
|
|
|
1503 *
|
|
|
1504 * \sa SDL_CopyGPUBufferToBuffer
|
|
|
1505 */
|
|
|
1506 typedef struct SDL_GPUBufferLocation
|
|
|
1507 {
|
|
|
1508 SDL_GPUBuffer *buffer; /**< The buffer. */
|
|
|
1509 Uint32 offset; /**< The starting byte within the buffer. */
|
|
|
1510 } SDL_GPUBufferLocation;
|
|
|
1511
|
|
|
1512 /**
|
|
|
1513 * A structure specifying a region of a buffer.
|
|
|
1514 *
|
|
|
1515 * Used when transferring data to or from buffers.
|
|
|
1516 *
|
|
|
1517 * \since This struct is available since SDL 3.2.0.
|
|
|
1518 *
|
|
|
1519 * \sa SDL_UploadToGPUBuffer
|
|
|
1520 * \sa SDL_DownloadFromGPUBuffer
|
|
|
1521 */
|
|
|
1522 typedef struct SDL_GPUBufferRegion
|
|
|
1523 {
|
|
|
1524 SDL_GPUBuffer *buffer; /**< The buffer. */
|
|
|
1525 Uint32 offset; /**< The starting byte within the buffer. */
|
|
|
1526 Uint32 size; /**< The size in bytes of the region. */
|
|
|
1527 } SDL_GPUBufferRegion;
|
|
|
1528
|
|
|
1529 /**
|
|
|
1530 * A structure specifying the parameters of an indirect draw command.
|
|
|
1531 *
|
|
|
1532 * Note that the `first_vertex` and `first_instance` parameters are NOT
|
|
|
1533 * compatible with built-in vertex/instance ID variables in shaders (for
|
|
|
1534 * example, SV_VertexID); GPU APIs and shader languages do not define these
|
|
|
1535 * built-in variables consistently, so if your shader depends on them, the
|
|
|
1536 * only way to keep behavior consistent and portable is to always pass 0 for
|
|
|
1537 * the correlating parameter in the draw calls.
|
|
|
1538 *
|
|
|
1539 * \since This struct is available since SDL 3.2.0.
|
|
|
1540 *
|
|
|
1541 * \sa SDL_DrawGPUPrimitivesIndirect
|
|
|
1542 */
|
|
|
1543 typedef struct SDL_GPUIndirectDrawCommand
|
|
|
1544 {
|
|
|
1545 Uint32 num_vertices; /**< The number of vertices to draw. */
|
|
|
1546 Uint32 num_instances; /**< The number of instances to draw. */
|
|
|
1547 Uint32 first_vertex; /**< The index of the first vertex to draw. */
|
|
|
1548 Uint32 first_instance; /**< The ID of the first instance to draw. */
|
|
|
1549 } SDL_GPUIndirectDrawCommand;
|
|
|
1550
|
|
|
1551 /**
|
|
|
1552 * A structure specifying the parameters of an indexed indirect draw command.
|
|
|
1553 *
|
|
|
1554 * Note that the `first_vertex` and `first_instance` parameters are NOT
|
|
|
1555 * compatible with built-in vertex/instance ID variables in shaders (for
|
|
|
1556 * example, SV_VertexID); GPU APIs and shader languages do not define these
|
|
|
1557 * built-in variables consistently, so if your shader depends on them, the
|
|
|
1558 * only way to keep behavior consistent and portable is to always pass 0 for
|
|
|
1559 * the correlating parameter in the draw calls.
|
|
|
1560 *
|
|
|
1561 * \since This struct is available since SDL 3.2.0.
|
|
|
1562 *
|
|
|
1563 * \sa SDL_DrawGPUIndexedPrimitivesIndirect
|
|
|
1564 */
|
|
|
1565 typedef struct SDL_GPUIndexedIndirectDrawCommand
|
|
|
1566 {
|
|
|
1567 Uint32 num_indices; /**< The number of indices to draw per instance. */
|
|
|
1568 Uint32 num_instances; /**< The number of instances to draw. */
|
|
|
1569 Uint32 first_index; /**< The base index within the index buffer. */
|
|
|
1570 Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */
|
|
|
1571 Uint32 first_instance; /**< The ID of the first instance to draw. */
|
|
|
1572 } SDL_GPUIndexedIndirectDrawCommand;
|
|
|
1573
|
|
|
1574 /**
|
|
|
1575 * A structure specifying the parameters of an indexed dispatch command.
|
|
|
1576 *
|
|
|
1577 * \since This struct is available since SDL 3.2.0.
|
|
|
1578 *
|
|
|
1579 * \sa SDL_DispatchGPUComputeIndirect
|
|
|
1580 */
|
|
|
1581 typedef struct SDL_GPUIndirectDispatchCommand
|
|
|
1582 {
|
|
|
1583 Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */
|
|
|
1584 Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */
|
|
|
1585 Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */
|
|
|
1586 } SDL_GPUIndirectDispatchCommand;
|
|
|
1587
|
|
|
1588 /* State structures */
|
|
|
1589
|
|
|
1590 /**
|
|
|
1591 * A structure specifying the parameters of a sampler.
|
|
|
1592 *
|
|
|
1593 * Note that mip_lod_bias is a no-op for the Metal driver. For Metal, LOD bias
|
|
|
1594 * must be applied via shader instead.
|
|
|
1595 *
|
|
|
1596 * \since This function is available since SDL 3.2.0.
|
|
|
1597 *
|
|
|
1598 * \sa SDL_CreateGPUSampler
|
|
|
1599 * \sa SDL_GPUFilter
|
|
|
1600 * \sa SDL_GPUSamplerMipmapMode
|
|
|
1601 * \sa SDL_GPUSamplerAddressMode
|
|
|
1602 * \sa SDL_GPUCompareOp
|
|
|
1603 */
|
|
|
1604 typedef struct SDL_GPUSamplerCreateInfo
|
|
|
1605 {
|
|
|
1606 SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */
|
|
|
1607 SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */
|
|
|
1608 SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */
|
|
|
1609 SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */
|
|
|
1610 SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */
|
|
|
1611 SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */
|
|
|
1612 float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */
|
|
|
1613 float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */
|
|
|
1614 SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */
|
|
|
1615 float min_lod; /**< Clamps the minimum of the computed LOD value. */
|
|
|
1616 float max_lod; /**< Clamps the maximum of the computed LOD value. */
|
|
|
1617 bool enable_anisotropy; /**< true to enable anisotropic filtering. */
|
|
|
1618 bool enable_compare; /**< true to enable comparison against a reference value during lookups. */
|
|
|
1619 Uint8 padding1;
|
|
|
1620 Uint8 padding2;
|
|
|
1621
|
|
|
1622 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1623 } SDL_GPUSamplerCreateInfo;
|
|
|
1624
|
|
|
1625 /**
|
|
|
1626 * A structure specifying the parameters of vertex buffers used in a graphics
|
|
|
1627 * pipeline.
|
|
|
1628 *
|
|
|
1629 * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of
|
|
|
1630 * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with
|
|
|
1631 * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be
|
|
|
1632 * used by the vertex buffers you pass in.
|
|
|
1633 *
|
|
|
1634 * Vertex attributes are linked to buffers via the buffer_slot field of
|
|
|
1635 * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of
|
|
|
1636 * 0, then that attribute belongs to the vertex buffer bound at slot 0.
|
|
|
1637 *
|
|
|
1638 * \since This struct is available since SDL 3.2.0.
|
|
|
1639 *
|
|
|
1640 * \sa SDL_GPUVertexAttribute
|
|
|
1641 * \sa SDL_GPUVertexInputRate
|
|
|
1642 */
|
|
|
1643 typedef struct SDL_GPUVertexBufferDescription
|
|
|
1644 {
|
|
|
1645 Uint32 slot; /**< The binding slot of the vertex buffer. */
|
|
|
1646 Uint32 pitch; /**< The size of a single element + the offset between elements. */
|
|
|
1647 SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */
|
|
|
1648 Uint32 instance_step_rate; /**< Reserved for future use. Must be set to 0. */
|
|
|
1649 } SDL_GPUVertexBufferDescription;
|
|
|
1650
|
|
|
1651 /**
|
|
|
1652 * A structure specifying a vertex attribute.
|
|
|
1653 *
|
|
|
1654 * All vertex attribute locations provided to an SDL_GPUVertexInputState must
|
|
|
1655 * be unique.
|
|
|
1656 *
|
|
|
1657 * \since This struct is available since SDL 3.2.0.
|
|
|
1658 *
|
|
|
1659 * \sa SDL_GPUVertexBufferDescription
|
|
|
1660 * \sa SDL_GPUVertexInputState
|
|
|
1661 * \sa SDL_GPUVertexElementFormat
|
|
|
1662 */
|
|
|
1663 typedef struct SDL_GPUVertexAttribute
|
|
|
1664 {
|
|
|
1665 Uint32 location; /**< The shader input location index. */
|
|
|
1666 Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */
|
|
|
1667 SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */
|
|
|
1668 Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */
|
|
|
1669 } SDL_GPUVertexAttribute;
|
|
|
1670
|
|
|
1671 /**
|
|
|
1672 * A structure specifying the parameters of a graphics pipeline vertex input
|
|
|
1673 * state.
|
|
|
1674 *
|
|
|
1675 * \since This struct is available since SDL 3.2.0.
|
|
|
1676 *
|
|
|
1677 * \sa SDL_GPUGraphicsPipelineCreateInfo
|
|
|
1678 * \sa SDL_GPUVertexBufferDescription
|
|
|
1679 * \sa SDL_GPUVertexAttribute
|
|
|
1680 */
|
|
|
1681 typedef struct SDL_GPUVertexInputState
|
|
|
1682 {
|
|
|
1683 const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */
|
|
|
1684 Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */
|
|
|
1685 const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */
|
|
|
1686 Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */
|
|
|
1687 } SDL_GPUVertexInputState;
|
|
|
1688
|
|
|
1689 /**
|
|
|
1690 * A structure specifying the stencil operation state of a graphics pipeline.
|
|
|
1691 *
|
|
|
1692 * \since This struct is available since SDL 3.2.0.
|
|
|
1693 *
|
|
|
1694 * \sa SDL_GPUDepthStencilState
|
|
|
1695 */
|
|
|
1696 typedef struct SDL_GPUStencilOpState
|
|
|
1697 {
|
|
|
1698 SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */
|
|
|
1699 SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */
|
|
|
1700 SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */
|
|
|
1701 SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */
|
|
|
1702 } SDL_GPUStencilOpState;
|
|
|
1703
|
|
|
1704 /**
|
|
|
1705 * A structure specifying the blend state of a color target.
|
|
|
1706 *
|
|
|
1707 * \since This struct is available since SDL 3.2.0.
|
|
|
1708 *
|
|
|
1709 * \sa SDL_GPUColorTargetDescription
|
|
|
1710 * \sa SDL_GPUBlendFactor
|
|
|
1711 * \sa SDL_GPUBlendOp
|
|
|
1712 * \sa SDL_GPUColorComponentFlags
|
|
|
1713 */
|
|
|
1714 typedef struct SDL_GPUColorTargetBlendState
|
|
|
1715 {
|
|
|
1716 SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */
|
|
|
1717 SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */
|
|
|
1718 SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */
|
|
|
1719 SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */
|
|
|
1720 SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */
|
|
|
1721 SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */
|
|
|
1722 SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */
|
|
|
1723 bool enable_blend; /**< Whether blending is enabled for the color target. */
|
|
|
1724 bool enable_color_write_mask; /**< Whether the color write mask is enabled. */
|
|
|
1725 Uint8 padding1;
|
|
|
1726 Uint8 padding2;
|
|
|
1727 } SDL_GPUColorTargetBlendState;
|
|
|
1728
|
|
|
1729
|
|
|
1730 /**
|
|
|
1731 * A structure specifying code and metadata for creating a shader object.
|
|
|
1732 *
|
|
|
1733 * \since This struct is available since SDL 3.2.0.
|
|
|
1734 *
|
|
|
1735 * \sa SDL_CreateGPUShader
|
|
|
1736 * \sa SDL_GPUShaderFormat
|
|
|
1737 * \sa SDL_GPUShaderStage
|
|
|
1738 */
|
|
|
1739 typedef struct SDL_GPUShaderCreateInfo
|
|
|
1740 {
|
|
|
1741 size_t code_size; /**< The size in bytes of the code pointed to. */
|
|
|
1742 const Uint8 *code; /**< A pointer to shader code. */
|
|
|
1743 const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */
|
|
|
1744 SDL_GPUShaderFormat format; /**< The format of the shader code. */
|
|
|
1745 SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */
|
|
|
1746 Uint32 num_samplers; /**< The number of samplers defined in the shader. */
|
|
|
1747 Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */
|
|
|
1748 Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */
|
|
|
1749 Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */
|
|
|
1750
|
|
|
1751 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1752 } SDL_GPUShaderCreateInfo;
|
|
|
1753
|
|
|
1754 /**
|
|
|
1755 * A structure specifying the parameters of a texture.
|
|
|
1756 *
|
|
|
1757 * Usage flags can be bitwise OR'd together for combinations of usages. Note
|
|
|
1758 * that certain usage combinations are invalid, for example SAMPLER and
|
|
|
1759 * GRAPHICS_STORAGE.
|
|
|
1760 *
|
|
|
1761 * \since This struct is available since SDL 3.2.0.
|
|
|
1762 *
|
|
|
1763 * \sa SDL_CreateGPUTexture
|
|
|
1764 * \sa SDL_GPUTextureType
|
|
|
1765 * \sa SDL_GPUTextureFormat
|
|
|
1766 * \sa SDL_GPUTextureUsageFlags
|
|
|
1767 * \sa SDL_GPUSampleCount
|
|
|
1768 */
|
|
|
1769 typedef struct SDL_GPUTextureCreateInfo
|
|
|
1770 {
|
|
|
1771 SDL_GPUTextureType type; /**< The base dimensionality of the texture. */
|
|
|
1772 SDL_GPUTextureFormat format; /**< The pixel format of the texture. */
|
|
|
1773 SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */
|
|
|
1774 Uint32 width; /**< The width of the texture. */
|
|
|
1775 Uint32 height; /**< The height of the texture. */
|
|
|
1776 Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */
|
|
|
1777 Uint32 num_levels; /**< The number of mip levels in the texture. */
|
|
|
1778 SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */
|
|
|
1779
|
|
|
1780 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1781 } SDL_GPUTextureCreateInfo;
|
|
|
1782
|
|
|
1783 /**
|
|
|
1784 * A structure specifying the parameters of a buffer.
|
|
|
1785 *
|
|
|
1786 * Usage flags can be bitwise OR'd together for combinations of usages. Note
|
|
|
1787 * that certain combinations are invalid, for example VERTEX and INDEX.
|
|
|
1788 *
|
|
|
1789 * \since This struct is available since SDL 3.2.0.
|
|
|
1790 *
|
|
|
1791 * \sa SDL_CreateGPUBuffer
|
|
|
1792 * \sa SDL_GPUBufferUsageFlags
|
|
|
1793 */
|
|
|
1794 typedef struct SDL_GPUBufferCreateInfo
|
|
|
1795 {
|
|
|
1796 SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */
|
|
|
1797 Uint32 size; /**< The size in bytes of the buffer. */
|
|
|
1798
|
|
|
1799 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1800 } SDL_GPUBufferCreateInfo;
|
|
|
1801
|
|
|
1802 /**
|
|
|
1803 * A structure specifying the parameters of a transfer buffer.
|
|
|
1804 *
|
|
|
1805 * \since This struct is available since SDL 3.2.0.
|
|
|
1806 *
|
|
|
1807 * \sa SDL_CreateGPUTransferBuffer
|
|
|
1808 */
|
|
|
1809 typedef struct SDL_GPUTransferBufferCreateInfo
|
|
|
1810 {
|
|
|
1811 SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */
|
|
|
1812 Uint32 size; /**< The size in bytes of the transfer buffer. */
|
|
|
1813
|
|
|
1814 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1815 } SDL_GPUTransferBufferCreateInfo;
|
|
|
1816
|
|
|
1817 /* Pipeline state structures */
|
|
|
1818
|
|
|
1819 /**
|
|
|
1820 * A structure specifying the parameters of the graphics pipeline rasterizer
|
|
|
1821 * state.
|
|
|
1822 *
|
|
|
1823 * Note that SDL_GPU_FILLMODE_LINE is not supported on many Android devices.
|
|
|
1824 * For those devices, the fill mode will automatically fall back to FILL.
|
|
|
1825 *
|
|
|
1826 * Also note that the D3D12 driver will enable depth clamping even if
|
|
|
1827 * enable_depth_clip is true. If you need this clamp+clip behavior, consider
|
|
|
1828 * enabling depth clip and then manually clamping depth in your fragment
|
|
|
1829 * shaders on Metal and Vulkan.
|
|
|
1830 *
|
|
|
1831 * \since This struct is available since SDL 3.2.0.
|
|
|
1832 *
|
|
|
1833 * \sa SDL_GPUGraphicsPipelineCreateInfo
|
|
|
1834 */
|
|
|
1835 typedef struct SDL_GPURasterizerState
|
|
|
1836 {
|
|
|
1837 SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */
|
|
|
1838 SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */
|
|
|
1839 SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */
|
|
|
1840 float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */
|
|
|
1841 float depth_bias_clamp; /**< The maximum depth bias of a fragment. */
|
|
|
1842 float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */
|
|
|
1843 bool enable_depth_bias; /**< true to bias fragment depth values. */
|
|
|
1844 bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */
|
|
|
1845 Uint8 padding1;
|
|
|
1846 Uint8 padding2;
|
|
|
1847 } SDL_GPURasterizerState;
|
|
|
1848
|
|
|
1849 /**
|
|
|
1850 * A structure specifying the parameters of the graphics pipeline multisample
|
|
|
1851 * state.
|
|
|
1852 *
|
|
|
1853 * \since This struct is available since SDL 3.2.0.
|
|
|
1854 *
|
|
|
1855 * \sa SDL_GPUGraphicsPipelineCreateInfo
|
|
|
1856 */
|
|
|
1857 typedef struct SDL_GPUMultisampleState
|
|
|
1858 {
|
|
|
1859 SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */
|
|
|
1860 Uint32 sample_mask; /**< Reserved for future use. Must be set to 0. */
|
|
|
1861 bool enable_mask; /**< Reserved for future use. Must be set to false. */
|
|
|
1862 bool enable_alpha_to_coverage; /**< true enables the alpha-to-coverage feature. */
|
|
|
1863 Uint8 padding2;
|
|
|
1864 Uint8 padding3;
|
|
|
1865 } SDL_GPUMultisampleState;
|
|
|
1866
|
|
|
1867 /**
|
|
|
1868 * A structure specifying the parameters of the graphics pipeline depth
|
|
|
1869 * stencil state.
|
|
|
1870 *
|
|
|
1871 * \since This struct is available since SDL 3.2.0.
|
|
|
1872 *
|
|
|
1873 * \sa SDL_GPUGraphicsPipelineCreateInfo
|
|
|
1874 */
|
|
|
1875 typedef struct SDL_GPUDepthStencilState
|
|
|
1876 {
|
|
|
1877 SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */
|
|
|
1878 SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */
|
|
|
1879 SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */
|
|
|
1880 Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */
|
|
|
1881 Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */
|
|
|
1882 bool enable_depth_test; /**< true enables the depth test. */
|
|
|
1883 bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */
|
|
|
1884 bool enable_stencil_test; /**< true enables the stencil test. */
|
|
|
1885 Uint8 padding1;
|
|
|
1886 Uint8 padding2;
|
|
|
1887 Uint8 padding3;
|
|
|
1888 } SDL_GPUDepthStencilState;
|
|
|
1889
|
|
|
1890 /**
|
|
|
1891 * A structure specifying the parameters of color targets used in a graphics
|
|
|
1892 * pipeline.
|
|
|
1893 *
|
|
|
1894 * \since This struct is available since SDL 3.2.0.
|
|
|
1895 *
|
|
|
1896 * \sa SDL_GPUGraphicsPipelineTargetInfo
|
|
|
1897 */
|
|
|
1898 typedef struct SDL_GPUColorTargetDescription
|
|
|
1899 {
|
|
|
1900 SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */
|
|
|
1901 SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */
|
|
|
1902 } SDL_GPUColorTargetDescription;
|
|
|
1903
|
|
|
1904 /**
|
|
|
1905 * A structure specifying the descriptions of render targets used in a
|
|
|
1906 * graphics pipeline.
|
|
|
1907 *
|
|
|
1908 * \since This struct is available since SDL 3.2.0.
|
|
|
1909 *
|
|
|
1910 * \sa SDL_GPUGraphicsPipelineCreateInfo
|
|
|
1911 * \sa SDL_GPUColorTargetDescription
|
|
|
1912 * \sa SDL_GPUTextureFormat
|
|
|
1913 */
|
|
|
1914 typedef struct SDL_GPUGraphicsPipelineTargetInfo
|
|
|
1915 {
|
|
|
1916 const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */
|
|
|
1917 Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */
|
|
|
1918 SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */
|
|
|
1919 bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */
|
|
|
1920 Uint8 padding1;
|
|
|
1921 Uint8 padding2;
|
|
|
1922 Uint8 padding3;
|
|
|
1923 } SDL_GPUGraphicsPipelineTargetInfo;
|
|
|
1924
|
|
|
1925 /**
|
|
|
1926 * A structure specifying the parameters of a graphics pipeline state.
|
|
|
1927 *
|
|
|
1928 * \since This struct is available since SDL 3.2.0.
|
|
|
1929 *
|
|
|
1930 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
1931 * \sa SDL_GPUShader
|
|
|
1932 * \sa SDL_GPUVertexInputState
|
|
|
1933 * \sa SDL_GPUPrimitiveType
|
|
|
1934 * \sa SDL_GPURasterizerState
|
|
|
1935 * \sa SDL_GPUMultisampleState
|
|
|
1936 * \sa SDL_GPUDepthStencilState
|
|
|
1937 * \sa SDL_GPUGraphicsPipelineTargetInfo
|
|
|
1938 */
|
|
|
1939 typedef struct SDL_GPUGraphicsPipelineCreateInfo
|
|
|
1940 {
|
|
|
1941 SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */
|
|
|
1942 SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */
|
|
|
1943 SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */
|
|
|
1944 SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */
|
|
|
1945 SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */
|
|
|
1946 SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */
|
|
|
1947 SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */
|
|
|
1948 SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */
|
|
|
1949
|
|
|
1950 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1951 } SDL_GPUGraphicsPipelineCreateInfo;
|
|
|
1952
|
|
|
1953 /**
|
|
|
1954 * A structure specifying the parameters of a compute pipeline state.
|
|
|
1955 *
|
|
|
1956 * \since This struct is available since SDL 3.2.0.
|
|
|
1957 *
|
|
|
1958 * \sa SDL_CreateGPUComputePipeline
|
|
|
1959 * \sa SDL_GPUShaderFormat
|
|
|
1960 */
|
|
|
1961 typedef struct SDL_GPUComputePipelineCreateInfo
|
|
|
1962 {
|
|
|
1963 size_t code_size; /**< The size in bytes of the compute shader code pointed to. */
|
|
|
1964 const Uint8 *code; /**< A pointer to compute shader code. */
|
|
|
1965 const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */
|
|
|
1966 SDL_GPUShaderFormat format; /**< The format of the compute shader code. */
|
|
|
1967 Uint32 num_samplers; /**< The number of samplers defined in the shader. */
|
|
|
1968 Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */
|
|
|
1969 Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */
|
|
|
1970 Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */
|
|
|
1971 Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */
|
|
|
1972 Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */
|
|
|
1973 Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */
|
|
|
1974 Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */
|
|
|
1975 Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */
|
|
|
1976
|
|
|
1977 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
1978 } SDL_GPUComputePipelineCreateInfo;
|
|
|
1979
|
|
|
1980 /**
|
|
|
1981 * A structure specifying the parameters of a color target used by a render
|
|
|
1982 * pass.
|
|
|
1983 *
|
|
|
1984 * The load_op field determines what is done with the texture at the beginning
|
|
|
1985 * of the render pass.
|
|
|
1986 *
|
|
|
1987 * - LOAD: Loads the data currently in the texture. Not recommended for
|
|
|
1988 * multisample textures as it requires significant memory bandwidth.
|
|
|
1989 * - CLEAR: Clears the texture to a single color.
|
|
|
1990 * - DONT_CARE: The driver will do whatever it wants with the texture memory.
|
|
|
1991 * This is a good option if you know that every single pixel will be touched
|
|
|
1992 * in the render pass.
|
|
|
1993 *
|
|
|
1994 * The store_op field determines what is done with the color results of the
|
|
|
1995 * render pass.
|
|
|
1996 *
|
|
|
1997 * - STORE: Stores the results of the render pass in the texture. Not
|
|
|
1998 * recommended for multisample textures as it requires significant memory
|
|
|
1999 * bandwidth.
|
|
|
2000 * - DONT_CARE: The driver will do whatever it wants with the texture memory.
|
|
|
2001 * This is often a good option for depth/stencil textures.
|
|
|
2002 * - RESOLVE: Resolves a multisample texture into resolve_texture, which must
|
|
|
2003 * have a sample count of 1. Then the driver may discard the multisample
|
|
|
2004 * texture memory. This is the most performant method of resolving a
|
|
|
2005 * multisample target.
|
|
|
2006 * - RESOLVE_AND_STORE: Resolves a multisample texture into the
|
|
|
2007 * resolve_texture, which must have a sample count of 1. Then the driver
|
|
|
2008 * stores the multisample texture's contents. Not recommended as it requires
|
|
|
2009 * significant memory bandwidth.
|
|
|
2010 *
|
|
|
2011 * \since This struct is available since SDL 3.2.0.
|
|
|
2012 *
|
|
|
2013 * \sa SDL_BeginGPURenderPass
|
|
|
2014 * \sa SDL_FColor
|
|
|
2015 */
|
|
|
2016 typedef struct SDL_GPUColorTargetInfo
|
|
|
2017 {
|
|
|
2018 SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */
|
|
|
2019 Uint32 mip_level; /**< The mip level to use as a color target. */
|
|
|
2020 Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */
|
|
|
2021 SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */
|
|
|
2022 SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */
|
|
|
2023 SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */
|
|
|
2024 SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */
|
|
|
2025 Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */
|
|
|
2026 Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */
|
|
|
2027 bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */
|
|
|
2028 bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */
|
|
|
2029 Uint8 padding1;
|
|
|
2030 Uint8 padding2;
|
|
|
2031 } SDL_GPUColorTargetInfo;
|
|
|
2032
|
|
|
2033 /**
|
|
|
2034 * A structure specifying the parameters of a depth-stencil target used by a
|
|
|
2035 * render pass.
|
|
|
2036 *
|
|
|
2037 * The load_op field determines what is done with the depth contents of the
|
|
|
2038 * texture at the beginning of the render pass.
|
|
|
2039 *
|
|
|
2040 * - LOAD: Loads the depth values currently in the texture.
|
|
|
2041 * - CLEAR: Clears the texture to a single depth.
|
|
|
2042 * - DONT_CARE: The driver will do whatever it wants with the memory. This is
|
|
|
2043 * a good option if you know that every single pixel will be touched in the
|
|
|
2044 * render pass.
|
|
|
2045 *
|
|
|
2046 * The store_op field determines what is done with the depth results of the
|
|
|
2047 * render pass.
|
|
|
2048 *
|
|
|
2049 * - STORE: Stores the depth results in the texture.
|
|
|
2050 * - DONT_CARE: The driver will do whatever it wants with the depth results.
|
|
|
2051 * This is often a good option for depth/stencil textures that don't need to
|
|
|
2052 * be reused again.
|
|
|
2053 *
|
|
|
2054 * The stencil_load_op field determines what is done with the stencil contents
|
|
|
2055 * of the texture at the beginning of the render pass.
|
|
|
2056 *
|
|
|
2057 * - LOAD: Loads the stencil values currently in the texture.
|
|
|
2058 * - CLEAR: Clears the stencil values to a single value.
|
|
|
2059 * - DONT_CARE: The driver will do whatever it wants with the memory. This is
|
|
|
2060 * a good option if you know that every single pixel will be touched in the
|
|
|
2061 * render pass.
|
|
|
2062 *
|
|
|
2063 * The stencil_store_op field determines what is done with the stencil results
|
|
|
2064 * of the render pass.
|
|
|
2065 *
|
|
|
2066 * - STORE: Stores the stencil results in the texture.
|
|
|
2067 * - DONT_CARE: The driver will do whatever it wants with the stencil results.
|
|
|
2068 * This is often a good option for depth/stencil textures that don't need to
|
|
|
2069 * be reused again.
|
|
|
2070 *
|
|
|
2071 * Note that depth/stencil targets do not support multisample resolves.
|
|
|
2072 *
|
|
|
2073 * Due to ABI limitations, depth textures with more than 255 layers are not
|
|
|
2074 * supported.
|
|
|
2075 *
|
|
|
2076 * \since This struct is available since SDL 3.2.0.
|
|
|
2077 *
|
|
|
2078 * \sa SDL_BeginGPURenderPass
|
|
|
2079 */
|
|
|
2080 typedef struct SDL_GPUDepthStencilTargetInfo
|
|
|
2081 {
|
|
|
2082 SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */
|
|
|
2083 float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */
|
|
|
2084 SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */
|
|
|
2085 SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */
|
|
|
2086 SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */
|
|
|
2087 SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */
|
|
|
2088 bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */
|
|
|
2089 Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */
|
|
|
2090 Uint8 mip_level; /**< The mip level to use as the depth stencil target. */
|
|
|
2091 Uint8 layer; /**< The layer index to use as the depth stencil target. */
|
|
|
2092 } SDL_GPUDepthStencilTargetInfo;
|
|
|
2093
|
|
|
2094 /**
|
|
|
2095 * A structure containing parameters for a blit command.
|
|
|
2096 *
|
|
|
2097 * \since This struct is available since SDL 3.2.0.
|
|
|
2098 *
|
|
|
2099 * \sa SDL_BlitGPUTexture
|
|
|
2100 */
|
|
|
2101 typedef struct SDL_GPUBlitInfo {
|
|
|
2102 SDL_GPUBlitRegion source; /**< The source region for the blit. */
|
|
|
2103 SDL_GPUBlitRegion destination; /**< The destination region for the blit. */
|
|
|
2104 SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */
|
|
|
2105 SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */
|
|
|
2106 SDL_FlipMode flip_mode; /**< The flip mode for the source region. */
|
|
|
2107 SDL_GPUFilter filter; /**< The filter mode used when blitting. */
|
|
|
2108 bool cycle; /**< true cycles the destination texture if it is already bound. */
|
|
|
2109 Uint8 padding1;
|
|
|
2110 Uint8 padding2;
|
|
|
2111 Uint8 padding3;
|
|
|
2112 } SDL_GPUBlitInfo;
|
|
|
2113
|
|
|
2114 /* Binding structs */
|
|
|
2115
|
|
|
2116 /**
|
|
|
2117 * A structure specifying parameters in a buffer binding call.
|
|
|
2118 *
|
|
|
2119 * \since This struct is available since SDL 3.2.0.
|
|
|
2120 *
|
|
|
2121 * \sa SDL_BindGPUVertexBuffers
|
|
|
2122 * \sa SDL_BindGPUIndexBuffer
|
|
|
2123 */
|
|
|
2124 typedef struct SDL_GPUBufferBinding
|
|
|
2125 {
|
|
|
2126 SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */
|
|
|
2127 Uint32 offset; /**< The starting byte of the data to bind in the buffer. */
|
|
|
2128 } SDL_GPUBufferBinding;
|
|
|
2129
|
|
|
2130 /**
|
|
|
2131 * A structure specifying parameters in a sampler binding call.
|
|
|
2132 *
|
|
|
2133 * \since This struct is available since SDL 3.2.0.
|
|
|
2134 *
|
|
|
2135 * \sa SDL_BindGPUVertexSamplers
|
|
|
2136 * \sa SDL_BindGPUFragmentSamplers
|
|
|
2137 * \sa SDL_GPUTexture
|
|
|
2138 * \sa SDL_GPUSampler
|
|
|
2139 */
|
|
|
2140 typedef struct SDL_GPUTextureSamplerBinding
|
|
|
2141 {
|
|
|
2142 SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */
|
|
|
2143 SDL_GPUSampler *sampler; /**< The sampler to bind. */
|
|
|
2144 } SDL_GPUTextureSamplerBinding;
|
|
|
2145
|
|
|
2146 /**
|
|
|
2147 * A structure specifying parameters related to binding buffers in a compute
|
|
|
2148 * pass.
|
|
|
2149 *
|
|
|
2150 * \since This struct is available since SDL 3.2.0.
|
|
|
2151 *
|
|
|
2152 * \sa SDL_BeginGPUComputePass
|
|
|
2153 */
|
|
|
2154 typedef struct SDL_GPUStorageBufferReadWriteBinding
|
|
|
2155 {
|
|
|
2156 SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */
|
|
|
2157 bool cycle; /**< true cycles the buffer if it is already bound. */
|
|
|
2158 Uint8 padding1;
|
|
|
2159 Uint8 padding2;
|
|
|
2160 Uint8 padding3;
|
|
|
2161 } SDL_GPUStorageBufferReadWriteBinding;
|
|
|
2162
|
|
|
2163 /**
|
|
|
2164 * A structure specifying parameters related to binding textures in a compute
|
|
|
2165 * pass.
|
|
|
2166 *
|
|
|
2167 * \since This struct is available since SDL 3.2.0.
|
|
|
2168 *
|
|
|
2169 * \sa SDL_BeginGPUComputePass
|
|
|
2170 */
|
|
|
2171 typedef struct SDL_GPUStorageTextureReadWriteBinding
|
|
|
2172 {
|
|
|
2173 SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */
|
|
|
2174 Uint32 mip_level; /**< The mip level index to bind. */
|
|
|
2175 Uint32 layer; /**< The layer index to bind. */
|
|
|
2176 bool cycle; /**< true cycles the texture if it is already bound. */
|
|
|
2177 Uint8 padding1;
|
|
|
2178 Uint8 padding2;
|
|
|
2179 Uint8 padding3;
|
|
|
2180 } SDL_GPUStorageTextureReadWriteBinding;
|
|
|
2181
|
|
|
2182 /* Functions */
|
|
|
2183
|
|
|
2184 /* Device */
|
|
|
2185
|
|
|
2186 /**
|
|
|
2187 * Checks for GPU runtime support.
|
|
|
2188 *
|
|
|
2189 * \param format_flags a bitflag indicating which shader formats the app is
|
|
|
2190 * able to provide.
|
|
|
2191 * \param name the preferred GPU driver, or NULL to let SDL pick the optimal
|
|
|
2192 * driver.
|
|
|
2193 * \returns true if supported, false otherwise.
|
|
|
2194 *
|
|
|
2195 * \since This function is available since SDL 3.2.0.
|
|
|
2196 *
|
|
|
2197 * \sa SDL_CreateGPUDevice
|
|
|
2198 */
|
|
|
2199 extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats(
|
|
|
2200 SDL_GPUShaderFormat format_flags,
|
|
|
2201 const char *name);
|
|
|
2202
|
|
|
2203 /**
|
|
|
2204 * Checks for GPU runtime support.
|
|
|
2205 *
|
|
|
2206 * \param props the properties to use.
|
|
|
2207 * \returns true if supported, false otherwise.
|
|
|
2208 *
|
|
|
2209 * \since This function is available since SDL 3.2.0.
|
|
|
2210 *
|
|
|
2211 * \sa SDL_CreateGPUDeviceWithProperties
|
|
|
2212 */
|
|
|
2213 extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties(
|
|
|
2214 SDL_PropertiesID props);
|
|
|
2215
|
|
|
2216 /**
|
|
|
2217 * Creates a GPU context.
|
|
|
2218 *
|
|
|
2219 * The GPU driver name can be one of the following:
|
|
|
2220 *
|
|
|
2221 * - "vulkan": [Vulkan](CategoryGPU#vulkan)
|
|
|
2222 * - "direct3d12": [D3D12](CategoryGPU#d3d12)
|
|
|
2223 * - "metal": [Metal](CategoryGPU#metal)
|
|
|
2224 * - NULL: let SDL pick the optimal driver
|
|
|
2225 *
|
|
|
2226 * \param format_flags a bitflag indicating which shader formats the app is
|
|
|
2227 * able to provide.
|
|
|
2228 * \param debug_mode enable debug mode properties and validations.
|
|
|
2229 * \param name the preferred GPU driver, or NULL to let SDL pick the optimal
|
|
|
2230 * driver.
|
|
|
2231 * \returns a GPU context on success or NULL on failure; call SDL_GetError()
|
|
|
2232 * for more information.
|
|
|
2233 *
|
|
|
2234 * \since This function is available since SDL 3.2.0.
|
|
|
2235 *
|
|
|
2236 * \sa SDL_CreateGPUDeviceWithProperties
|
|
|
2237 * \sa SDL_GetGPUShaderFormats
|
|
|
2238 * \sa SDL_GetGPUDeviceDriver
|
|
|
2239 * \sa SDL_DestroyGPUDevice
|
|
|
2240 * \sa SDL_GPUSupportsShaderFormats
|
|
|
2241 */
|
|
|
2242 extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice(
|
|
|
2243 SDL_GPUShaderFormat format_flags,
|
|
|
2244 bool debug_mode,
|
|
|
2245 const char *name);
|
|
|
2246
|
|
|
2247 /**
|
|
|
2248 * Creates a GPU context.
|
|
|
2249 *
|
|
|
2250 * These are the supported properties:
|
|
|
2251 *
|
|
|
2252 * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode
|
|
|
2253 * properties and validations, defaults to true.
|
|
|
2254 * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer
|
|
|
2255 * energy efficiency over maximum GPU performance, defaults to false.
|
|
|
2256 * - `SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN`: enable to automatically log
|
|
|
2257 * useful debug information on device creation, defaults to true.
|
|
|
2258 * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to
|
|
|
2259 * use, if a specific one is desired.
|
|
|
2260 * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN`: Enable Vulkan
|
|
|
2261 * device feature shaderClipDistance. If disabled, clip distances are not
|
|
|
2262 * supported in shader code: gl_ClipDistance[] built-ins of GLSL,
|
|
|
2263 * SV_ClipDistance0/1 semantics of HLSL and [[clip_distance]] attribute of
|
|
|
2264 * Metal. Disabling optional features allows the application to run on some
|
|
|
2265 * older Android devices. Defaults to true.
|
|
|
2266 * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN`: Enable
|
|
|
2267 * Vulkan device feature depthClamp. If disabled, there is no depth clamp
|
|
|
2268 * support and enable_depth_clip in SDL_GPURasterizerState must always be
|
|
|
2269 * set to true. Disabling optional features allows the application to run on
|
|
|
2270 * some older Android devices. Defaults to true.
|
|
|
2271 * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN`:
|
|
|
2272 * Enable Vulkan device feature drawIndirectFirstInstance. If disabled, the
|
|
|
2273 * argument first_instance of SDL_GPUIndirectDrawCommand must be set to
|
|
|
2274 * zero. Disabling optional features allows the application to run on some
|
|
|
2275 * older Android devices. Defaults to true.
|
|
|
2276 * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN`: Enable Vulkan
|
|
|
2277 * device feature samplerAnisotropy. If disabled, enable_anisotropy of
|
|
|
2278 * SDL_GPUSamplerCreateInfo must be set to false. Disabling optional
|
|
|
2279 * features allows the application to run on some older Android devices.
|
|
|
2280 * Defaults to true.
|
|
|
2281 *
|
|
|
2282 * These are the current shader format properties:
|
|
|
2283 *
|
|
|
2284 * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to
|
|
|
2285 * provide shaders for an NDA platform.
|
|
|
2286 * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to
|
|
|
2287 * provide SPIR-V shaders if applicable.
|
|
|
2288 * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to
|
|
|
2289 * provide DXBC shaders if applicable
|
|
|
2290 * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to
|
|
|
2291 * provide DXIL shaders if applicable.
|
|
|
2292 * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to
|
|
|
2293 * provide MSL shaders if applicable.
|
|
|
2294 * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to
|
|
|
2295 * provide Metal shader libraries if applicable.
|
|
|
2296 *
|
|
|
2297 * With the D3D12 backend:
|
|
|
2298 *
|
|
|
2299 * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to
|
|
|
2300 * use for all vertex semantics, default is "TEXCOORD".
|
|
|
2301 * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN`: By
|
|
|
2302 * default, Resourcing Binding Tier 2 is required for D3D12 support.
|
|
|
2303 * However, an application can set this property to true to enable Tier 1
|
|
|
2304 * support, if (and only if) the application uses 8 or fewer storage
|
|
|
2305 * resources across all shader stages. As of writing, this property is
|
|
|
2306 * useful for targeting Intel Haswell and Broadwell GPUs; other hardware
|
|
|
2307 * either supports Tier 2 Resource Binding or does not support D3D12 in any
|
|
|
2308 * capacity. Defaults to false.
|
|
|
2309 *
|
|
|
2310 * With the Vulkan backend:
|
|
|
2311 *
|
|
|
2312 * - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN`:
|
|
|
2313 * By default, Vulkan device enumeration includes drivers of all types,
|
|
|
2314 * including software renderers (for example, the Lavapipe Mesa driver).
|
|
|
2315 * This can be useful if your application _requires_ SDL_GPU, but if you can
|
|
|
2316 * provide your own fallback renderer (for example, an OpenGL renderer) this
|
|
|
2317 * property can be set to true. Defaults to false.
|
|
|
2318 * - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER`: a pointer to an
|
|
|
2319 * SDL_GPUVulkanOptions structure to be processed during device creation.
|
|
|
2320 * This allows configuring a variety of Vulkan-specific options such as
|
|
|
2321 * increasing the API version and opting into extensions aside from the
|
|
|
2322 * minimal set SDL requires.
|
|
|
2323 *
|
|
|
2324 * \param props the properties to use.
|
|
|
2325 * \returns a GPU context on success or NULL on failure; call SDL_GetError()
|
|
|
2326 * for more information.
|
|
|
2327 *
|
|
|
2328 * \since This function is available since SDL 3.2.0.
|
|
|
2329 *
|
|
|
2330 * \sa SDL_GetGPUShaderFormats
|
|
|
2331 * \sa SDL_GetGPUDeviceDriver
|
|
|
2332 * \sa SDL_DestroyGPUDevice
|
|
|
2333 * \sa SDL_GPUSupportsProperties
|
|
|
2334 */
|
|
|
2335 extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties(
|
|
|
2336 SDL_PropertiesID props);
|
|
|
2337
|
|
|
2338 #define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode"
|
|
|
2339 #define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower"
|
|
|
2340 #define SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN "SDL.gpu.device.create.verbose"
|
|
|
2341 #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name"
|
|
|
2342 #define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN "SDL.gpu.device.create.feature.clip_distance"
|
|
|
2343 #define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN "SDL.gpu.device.create.feature.depth_clamping"
|
|
|
2344 #define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN "SDL.gpu.device.create.feature.indirect_draw_first_instance"
|
|
|
2345 #define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN "SDL.gpu.device.create.feature.anisotropy"
|
|
|
2346 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private"
|
|
|
2347 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv"
|
|
|
2348 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc"
|
|
|
2349 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil"
|
|
|
2350 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl"
|
|
|
2351 #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib"
|
|
|
2352 #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN "SDL.gpu.device.create.d3d12.allowtier1resourcebinding"
|
|
|
2353 #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic"
|
|
|
2354 #define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN "SDL.gpu.device.create.vulkan.requirehardwareacceleration"
|
|
|
2355 #define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER "SDL.gpu.device.create.vulkan.options"
|
|
|
2356
|
|
|
2357
|
|
|
2358 /**
|
|
|
2359 * A structure specifying additional options when using Vulkan.
|
|
|
2360 *
|
|
|
2361 * When no such structure is provided, SDL will use Vulkan API version 1.0 and
|
|
|
2362 * a minimal set of features. The requested API version influences how the
|
|
|
2363 * feature_list is processed by SDL. When requesting API version 1.0, the
|
|
|
2364 * feature_list is ignored. Only the vulkan_10_physical_device_features and
|
|
|
2365 * the extension lists are used. When requesting API version 1.1, the
|
|
|
2366 * feature_list is scanned for feature structures introduced in Vulkan 1.1.
|
|
|
2367 * When requesting Vulkan 1.2 or higher, the feature_list is additionally
|
|
|
2368 * scanned for compound feature structs such as
|
|
|
2369 * VkPhysicalDeviceVulkan11Features. The device and instance extension lists,
|
|
|
2370 * as well as vulkan_10_physical_device_features, are always processed.
|
|
|
2371 *
|
|
|
2372 * \since This struct is available since SDL 3.4.0.
|
|
|
2373 */
|
|
|
2374 typedef struct SDL_GPUVulkanOptions
|
|
|
2375 {
|
|
|
2376 Uint32 vulkan_api_version; /**< The Vulkan API version to request for the instance. Use Vulkan's VK_MAKE_VERSION or VK_MAKE_API_VERSION. */
|
|
|
2377 void *feature_list; /**< Pointer to the first element of a chain of Vulkan feature structs. (Requires API version 1.1 or higher.)*/
|
|
|
2378 void *vulkan_10_physical_device_features; /**< Pointer to a VkPhysicalDeviceFeatures struct to enable additional Vulkan 1.0 features. */
|
|
|
2379 Uint32 device_extension_count; /**< Number of additional device extensions to require. */
|
|
|
2380 const char **device_extension_names; /**< Pointer to a list of additional device extensions to require. */
|
|
|
2381 Uint32 instance_extension_count; /**< Number of additional instance extensions to require. */
|
|
|
2382 const char **instance_extension_names; /**< Pointer to a list of additional instance extensions to require. */
|
|
|
2383 } SDL_GPUVulkanOptions;
|
|
|
2384
|
|
|
2385 /**
|
|
|
2386 * Destroys a GPU context previously returned by SDL_CreateGPUDevice.
|
|
|
2387 *
|
|
|
2388 * \param device a GPU Context to destroy.
|
|
|
2389 *
|
|
|
2390 * \since This function is available since SDL 3.2.0.
|
|
|
2391 *
|
|
|
2392 * \sa SDL_CreateGPUDevice
|
|
|
2393 */
|
|
|
2394 extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device);
|
|
|
2395
|
|
|
2396 /**
|
|
|
2397 * Get the number of GPU drivers compiled into SDL.
|
|
|
2398 *
|
|
|
2399 * \returns the number of built in GPU drivers.
|
|
|
2400 *
|
|
|
2401 * \since This function is available since SDL 3.2.0.
|
|
|
2402 *
|
|
|
2403 * \sa SDL_GetGPUDriver
|
|
|
2404 */
|
|
|
2405 extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void);
|
|
|
2406
|
|
|
2407 /**
|
|
|
2408 * Get the name of a built in GPU driver.
|
|
|
2409 *
|
|
|
2410 * The GPU drivers are presented in the order in which they are normally
|
|
|
2411 * checked during initialization.
|
|
|
2412 *
|
|
|
2413 * The names of drivers are all simple, low-ASCII identifiers, like "vulkan",
|
|
|
2414 * "metal" or "direct3d12". These never have Unicode characters, and are not
|
|
|
2415 * meant to be proper names.
|
|
|
2416 *
|
|
|
2417 * \param index the index of a GPU driver.
|
|
|
2418 * \returns the name of the GPU driver with the given **index**.
|
|
|
2419 *
|
|
|
2420 * \since This function is available since SDL 3.2.0.
|
|
|
2421 *
|
|
|
2422 * \sa SDL_GetNumGPUDrivers
|
|
|
2423 */
|
|
|
2424 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index);
|
|
|
2425
|
|
|
2426 /**
|
|
|
2427 * Returns the name of the backend used to create this GPU context.
|
|
|
2428 *
|
|
|
2429 * \param device a GPU context to query.
|
|
|
2430 * \returns the name of the device's driver, or NULL on error.
|
|
|
2431 *
|
|
|
2432 * \since This function is available since SDL 3.2.0.
|
|
|
2433 */
|
|
|
2434 extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device);
|
|
|
2435
|
|
|
2436 /**
|
|
|
2437 * Returns the supported shader formats for this GPU context.
|
|
|
2438 *
|
|
|
2439 * \param device a GPU context to query.
|
|
|
2440 * \returns a bitflag indicating which shader formats the driver is able to
|
|
|
2441 * consume.
|
|
|
2442 *
|
|
|
2443 * \since This function is available since SDL 3.2.0.
|
|
|
2444 */
|
|
|
2445 extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device);
|
|
|
2446
|
|
|
2447 /**
|
|
|
2448 * Get the properties associated with a GPU device.
|
|
|
2449 *
|
|
|
2450 * All properties are optional and may differ between GPU backends and SDL
|
|
|
2451 * versions.
|
|
|
2452 *
|
|
|
2453 * The following properties are provided by SDL:
|
|
|
2454 *
|
|
|
2455 * `SDL_PROP_GPU_DEVICE_NAME_STRING`: Contains the name of the underlying
|
|
|
2456 * device as reported by the system driver. This string has no standardized
|
|
|
2457 * format, is highly inconsistent between hardware devices and drivers, and is
|
|
|
2458 * able to change at any time. Do not attempt to parse this string as it is
|
|
|
2459 * bound to fail at some point in the future when system drivers are updated,
|
|
|
2460 * new hardware devices are introduced, or when SDL adds new GPU backends or
|
|
|
2461 * modifies existing ones.
|
|
|
2462 *
|
|
|
2463 * Strings that have been found in the wild include:
|
|
|
2464 *
|
|
|
2465 * - GTX 970
|
|
|
2466 * - GeForce GTX 970
|
|
|
2467 * - NVIDIA GeForce GTX 970
|
|
|
2468 * - Microsoft Direct3D12 (NVIDIA GeForce GTX 970)
|
|
|
2469 * - NVIDIA Graphics Device
|
|
|
2470 * - GeForce GPU
|
|
|
2471 * - P106-100
|
|
|
2472 * - AMD 15D8:C9
|
|
|
2473 * - AMD Custom GPU 0405
|
|
|
2474 * - AMD Radeon (TM) Graphics
|
|
|
2475 * - ASUS Radeon RX 470 Series
|
|
|
2476 * - Intel(R) Arc(tm) A380 Graphics (DG2)
|
|
|
2477 * - Virtio-GPU Venus (NVIDIA TITAN V)
|
|
|
2478 * - SwiftShader Device (LLVM 16.0.0)
|
|
|
2479 * - llvmpipe (LLVM 15.0.4, 256 bits)
|
|
|
2480 * - Microsoft Basic Render Driver
|
|
|
2481 * - unknown device
|
|
|
2482 *
|
|
|
2483 * The above list shows that the same device can have different formats, the
|
|
|
2484 * vendor name may or may not appear in the string, the included vendor name
|
|
|
2485 * may not be the vendor of the chipset on the device, some manufacturers
|
|
|
2486 * include pseudo-legal marks while others don't, some devices may not use a
|
|
|
2487 * marketing name in the string, the device string may be wrapped by the name
|
|
|
2488 * of a translation interface, the device may be emulated in software, or the
|
|
|
2489 * string may contain generic text that does not identify the device at all.
|
|
|
2490 *
|
|
|
2491 * `SDL_PROP_GPU_DEVICE_DRIVER_NAME_STRING`: Contains the self-reported name
|
|
|
2492 * of the underlying system driver.
|
|
|
2493 *
|
|
|
2494 * Strings that have been found in the wild include:
|
|
|
2495 *
|
|
|
2496 * - Intel Corporation
|
|
|
2497 * - Intel open-source Mesa driver
|
|
|
2498 * - Qualcomm Technologies Inc. Adreno Vulkan Driver
|
|
|
2499 * - MoltenVK
|
|
|
2500 * - Mali-G715
|
|
|
2501 * - venus
|
|
|
2502 *
|
|
|
2503 * `SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING`: Contains the self-reported
|
|
|
2504 * version of the underlying system driver. This is a relatively short version
|
|
|
2505 * string in an unspecified format. If SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING
|
|
|
2506 * is available then that property should be preferred over this one as it may
|
|
|
2507 * contain additional information that is useful for identifying the exact
|
|
|
2508 * driver version used.
|
|
|
2509 *
|
|
|
2510 * Strings that have been found in the wild include:
|
|
|
2511 *
|
|
|
2512 * - 53.0.0
|
|
|
2513 * - 0.405.2463
|
|
|
2514 * - 32.0.15.6614
|
|
|
2515 *
|
|
|
2516 * `SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING`: Contains the detailed version
|
|
|
2517 * information of the underlying system driver as reported by the driver. This
|
|
|
2518 * is an arbitrary string with no standardized format and it may contain
|
|
|
2519 * newlines. This property should be preferred over
|
|
|
2520 * SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING if it is available as it usually
|
|
|
2521 * contains the same information but in a format that is easier to read.
|
|
|
2522 *
|
|
|
2523 * Strings that have been found in the wild include:
|
|
|
2524 *
|
|
|
2525 * - 101.6559
|
|
|
2526 * - 1.2.11
|
|
|
2527 * - Mesa 21.2.2 (LLVM 12.0.1)
|
|
|
2528 * - Mesa 22.2.0-devel (git-f226222 2022-04-14 impish-oibaf-ppa)
|
|
|
2529 * - v1.r53p0-00eac0.824c4f31403fb1fbf8ee1042422c2129
|
|
|
2530 *
|
|
|
2531 * This string has also been observed to be a multiline string (which has a
|
|
|
2532 * trailing newline):
|
|
|
2533 *
|
|
|
2534 * ```
|
|
|
2535 * Driver Build: 85da404, I46ff5fc46f, 1606794520
|
|
|
2536 * Date: 11/30/20
|
|
|
2537 * Compiler Version: EV031.31.04.01
|
|
|
2538 * Driver Branch: promo490_3_Google
|
|
|
2539 * ```
|
|
|
2540 *
|
|
|
2541 * \param device a GPU context to query.
|
|
|
2542 * \returns a valid property ID on success or 0 on failure; call
|
|
|
2543 * SDL_GetError() for more information.
|
|
|
2544 *
|
|
|
2545 * \threadsafety It is safe to call this function from any thread.
|
|
|
2546 *
|
|
|
2547 * \since This function is available since SDL 3.4.0.
|
|
|
2548 */
|
|
|
2549 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGPUDeviceProperties(SDL_GPUDevice *device);
|
|
|
2550
|
|
|
2551 #define SDL_PROP_GPU_DEVICE_NAME_STRING "SDL.gpu.device.name"
|
|
|
2552 #define SDL_PROP_GPU_DEVICE_DRIVER_NAME_STRING "SDL.gpu.device.driver_name"
|
|
|
2553 #define SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING "SDL.gpu.device.driver_version"
|
|
|
2554 #define SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING "SDL.gpu.device.driver_info"
|
|
|
2555
|
|
|
2556
|
|
|
2557 /* State Creation */
|
|
|
2558
|
|
|
2559 /**
|
|
|
2560 * Creates a pipeline object to be used in a compute workflow.
|
|
|
2561 *
|
|
|
2562 * Shader resource bindings must be authored to follow a particular order
|
|
|
2563 * depending on the shader format.
|
|
|
2564 *
|
|
|
2565 * For SPIR-V shaders, use the following resource sets:
|
|
|
2566 *
|
|
|
2567 * - 0: Sampled textures, followed by read-only storage textures, followed by
|
|
|
2568 * read-only storage buffers
|
|
|
2569 * - 1: Read-write storage textures, followed by read-write storage buffers
|
|
|
2570 * - 2: Uniform buffers
|
|
|
2571 *
|
|
|
2572 * For DXBC and DXIL shaders, use the following register order:
|
|
|
2573 *
|
|
|
2574 * - (t[n], space0): Sampled textures, followed by read-only storage textures,
|
|
|
2575 * followed by read-only storage buffers
|
|
|
2576 * - (u[n], space1): Read-write storage textures, followed by read-write
|
|
|
2577 * storage buffers
|
|
|
2578 * - (b[n], space2): Uniform buffers
|
|
|
2579 *
|
|
|
2580 * For MSL/metallib, use the following order:
|
|
|
2581 *
|
|
|
2582 * - [[buffer]]: Uniform buffers, followed by read-only storage buffers,
|
|
|
2583 * followed by read-write storage buffers
|
|
|
2584 * - [[texture]]: Sampled textures, followed by read-only storage textures,
|
|
|
2585 * followed by read-write storage textures
|
|
|
2586 *
|
|
|
2587 * There are optional properties that can be provided through `props`. These
|
|
|
2588 * are the supported properties:
|
|
|
2589 *
|
|
|
2590 * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be
|
|
|
2591 * displayed in debugging tools.
|
|
|
2592 *
|
|
|
2593 * \param device a GPU Context.
|
|
|
2594 * \param createinfo a struct describing the state of the compute pipeline to
|
|
|
2595 * create.
|
|
|
2596 * \returns a compute pipeline object on success, or NULL on failure; call
|
|
|
2597 * SDL_GetError() for more information.
|
|
|
2598 *
|
|
|
2599 * \since This function is available since SDL 3.2.0.
|
|
|
2600 *
|
|
|
2601 * \sa SDL_BindGPUComputePipeline
|
|
|
2602 * \sa SDL_ReleaseGPUComputePipeline
|
|
|
2603 */
|
|
|
2604 extern SDL_DECLSPEC SDL_GPUComputePipeline * SDLCALL SDL_CreateGPUComputePipeline(
|
|
|
2605 SDL_GPUDevice *device,
|
|
|
2606 const SDL_GPUComputePipelineCreateInfo *createinfo);
|
|
|
2607
|
|
|
2608 #define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name"
|
|
|
2609
|
|
|
2610 /**
|
|
|
2611 * Creates a pipeline object to be used in a graphics workflow.
|
|
|
2612 *
|
|
|
2613 * There are optional properties that can be provided through `props`. These
|
|
|
2614 * are the supported properties:
|
|
|
2615 *
|
|
|
2616 * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be
|
|
|
2617 * displayed in debugging tools.
|
|
|
2618 *
|
|
|
2619 * \param device a GPU Context.
|
|
|
2620 * \param createinfo a struct describing the state of the graphics pipeline to
|
|
|
2621 * create.
|
|
|
2622 * \returns a graphics pipeline object on success, or NULL on failure; call
|
|
|
2623 * SDL_GetError() for more information.
|
|
|
2624 *
|
|
|
2625 * \since This function is available since SDL 3.2.0.
|
|
|
2626 *
|
|
|
2627 * \sa SDL_CreateGPUShader
|
|
|
2628 * \sa SDL_BindGPUGraphicsPipeline
|
|
|
2629 * \sa SDL_ReleaseGPUGraphicsPipeline
|
|
|
2630 */
|
|
|
2631 extern SDL_DECLSPEC SDL_GPUGraphicsPipeline * SDLCALL SDL_CreateGPUGraphicsPipeline(
|
|
|
2632 SDL_GPUDevice *device,
|
|
|
2633 const SDL_GPUGraphicsPipelineCreateInfo *createinfo);
|
|
|
2634
|
|
|
2635 #define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name"
|
|
|
2636
|
|
|
2637 /**
|
|
|
2638 * Creates a sampler object to be used when binding textures in a graphics
|
|
|
2639 * workflow.
|
|
|
2640 *
|
|
|
2641 * There are optional properties that can be provided through `props`. These
|
|
|
2642 * are the supported properties:
|
|
|
2643 *
|
|
|
2644 * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed
|
|
|
2645 * in debugging tools.
|
|
|
2646 *
|
|
|
2647 * \param device a GPU Context.
|
|
|
2648 * \param createinfo a struct describing the state of the sampler to create.
|
|
|
2649 * \returns a sampler object on success, or NULL on failure; call
|
|
|
2650 * SDL_GetError() for more information.
|
|
|
2651 *
|
|
|
2652 * \since This function is available since SDL 3.2.0.
|
|
|
2653 *
|
|
|
2654 * \sa SDL_BindGPUVertexSamplers
|
|
|
2655 * \sa SDL_BindGPUFragmentSamplers
|
|
|
2656 * \sa SDL_ReleaseGPUSampler
|
|
|
2657 */
|
|
|
2658 extern SDL_DECLSPEC SDL_GPUSampler * SDLCALL SDL_CreateGPUSampler(
|
|
|
2659 SDL_GPUDevice *device,
|
|
|
2660 const SDL_GPUSamplerCreateInfo *createinfo);
|
|
|
2661
|
|
|
2662 #define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name"
|
|
|
2663
|
|
|
2664 /**
|
|
|
2665 * Creates a shader to be used when creating a graphics pipeline.
|
|
|
2666 *
|
|
|
2667 * Shader resource bindings must be authored to follow a particular order
|
|
|
2668 * depending on the shader format.
|
|
|
2669 *
|
|
|
2670 * For SPIR-V shaders, use the following resource sets:
|
|
|
2671 *
|
|
|
2672 * For vertex shaders:
|
|
|
2673 *
|
|
|
2674 * - 0: Sampled textures, followed by storage textures, followed by storage
|
|
|
2675 * buffers
|
|
|
2676 * - 1: Uniform buffers
|
|
|
2677 *
|
|
|
2678 * For fragment shaders:
|
|
|
2679 *
|
|
|
2680 * - 2: Sampled textures, followed by storage textures, followed by storage
|
|
|
2681 * buffers
|
|
|
2682 * - 3: Uniform buffers
|
|
|
2683 *
|
|
|
2684 * For DXBC and DXIL shaders, use the following register order:
|
|
|
2685 *
|
|
|
2686 * For vertex shaders:
|
|
|
2687 *
|
|
|
2688 * - (t[n], space0): Sampled textures, followed by storage textures, followed
|
|
|
2689 * by storage buffers
|
|
|
2690 * - (s[n], space0): Samplers with indices corresponding to the sampled
|
|
|
2691 * textures
|
|
|
2692 * - (b[n], space1): Uniform buffers
|
|
|
2693 *
|
|
|
2694 * For pixel shaders:
|
|
|
2695 *
|
|
|
2696 * - (t[n], space2): Sampled textures, followed by storage textures, followed
|
|
|
2697 * by storage buffers
|
|
|
2698 * - (s[n], space2): Samplers with indices corresponding to the sampled
|
|
|
2699 * textures
|
|
|
2700 * - (b[n], space3): Uniform buffers
|
|
|
2701 *
|
|
|
2702 * For MSL/metallib, use the following order:
|
|
|
2703 *
|
|
|
2704 * - [[texture]]: Sampled textures, followed by storage textures
|
|
|
2705 * - [[sampler]]: Samplers with indices corresponding to the sampled textures
|
|
|
2706 * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0
|
|
|
2707 * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on.
|
|
|
2708 * Rather than manually authoring vertex buffer indices, use the
|
|
|
2709 * [[stage_in]] attribute which will automatically use the vertex input
|
|
|
2710 * information from the SDL_GPUGraphicsPipeline.
|
|
|
2711 *
|
|
|
2712 * Shader semantics other than system-value semantics do not matter in D3D12
|
|
|
2713 * and for ease of use the SDL implementation assumes that non system-value
|
|
|
2714 * semantics will all be TEXCOORD. If you are using HLSL as the shader source
|
|
|
2715 * language, your vertex semantics should start at TEXCOORD0 and increment
|
|
|
2716 * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic
|
|
|
2717 * prefix to something other than TEXCOORD you can use
|
|
|
2718 * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with
|
|
|
2719 * SDL_CreateGPUDeviceWithProperties().
|
|
|
2720 *
|
|
|
2721 * There are optional properties that can be provided through `props`. These
|
|
|
2722 * are the supported properties:
|
|
|
2723 *
|
|
|
2724 * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in
|
|
|
2725 * debugging tools.
|
|
|
2726 *
|
|
|
2727 * \param device a GPU Context.
|
|
|
2728 * \param createinfo a struct describing the state of the shader to create.
|
|
|
2729 * \returns a shader object on success, or NULL on failure; call
|
|
|
2730 * SDL_GetError() for more information.
|
|
|
2731 *
|
|
|
2732 * \since This function is available since SDL 3.2.0.
|
|
|
2733 *
|
|
|
2734 * \sa SDL_CreateGPUGraphicsPipeline
|
|
|
2735 * \sa SDL_ReleaseGPUShader
|
|
|
2736 */
|
|
|
2737 extern SDL_DECLSPEC SDL_GPUShader * SDLCALL SDL_CreateGPUShader(
|
|
|
2738 SDL_GPUDevice *device,
|
|
|
2739 const SDL_GPUShaderCreateInfo *createinfo);
|
|
|
2740
|
|
|
2741 #define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name"
|
|
|
2742
|
|
|
2743 /**
|
|
|
2744 * Creates a texture object to be used in graphics or compute workflows.
|
|
|
2745 *
|
|
|
2746 * The contents of this texture are undefined until data is written to the
|
|
|
2747 * texture, either via SDL_UploadToGPUTexture or by performing a render or
|
|
|
2748 * compute pass with this texture as a target.
|
|
|
2749 *
|
|
|
2750 * Note that certain combinations of usage flags are invalid. For example, a
|
|
|
2751 * texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags.
|
|
|
2752 *
|
|
|
2753 * If you request a sample count higher than the hardware supports, the
|
|
|
2754 * implementation will automatically fall back to the highest available sample
|
|
|
2755 * count.
|
|
|
2756 *
|
|
|
2757 * There are optional properties that can be provided through
|
|
|
2758 * SDL_GPUTextureCreateInfo's `props`. These are the supported properties:
|
|
|
2759 *
|
|
|
2760 * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if
|
|
|
2761 * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
|
|
|
2762 * to a color with this red intensity. Defaults to zero.
|
|
|
2763 * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if
|
|
|
2764 * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
|
|
|
2765 * to a color with this green intensity. Defaults to zero.
|
|
|
2766 * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if
|
|
|
2767 * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
|
|
|
2768 * to a color with this blue intensity. Defaults to zero.
|
|
|
2769 * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if
|
|
|
2770 * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
|
|
|
2771 * to a color with this alpha intensity. Defaults to zero.
|
|
|
2772 * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only)
|
|
|
2773 * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
|
|
|
2774 * the texture to a depth of this value. Defaults to zero.
|
|
|
2775 * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER`: (Direct3D 12
|
|
|
2776 * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET,
|
|
|
2777 * clear the texture to a stencil of this Uint8 value. Defaults to zero.
|
|
|
2778 * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed
|
|
|
2779 * in debugging tools.
|
|
|
2780 *
|
|
|
2781 * \param device a GPU Context.
|
|
|
2782 * \param createinfo a struct describing the state of the texture to create.
|
|
|
2783 * \returns a texture object on success, or NULL on failure; call
|
|
|
2784 * SDL_GetError() for more information.
|
|
|
2785 *
|
|
|
2786 * \since This function is available since SDL 3.2.0.
|
|
|
2787 *
|
|
|
2788 * \sa SDL_UploadToGPUTexture
|
|
|
2789 * \sa SDL_DownloadFromGPUTexture
|
|
|
2790 * \sa SDL_BeginGPURenderPass
|
|
|
2791 * \sa SDL_BeginGPUComputePass
|
|
|
2792 * \sa SDL_BindGPUVertexSamplers
|
|
|
2793 * \sa SDL_BindGPUVertexStorageTextures
|
|
|
2794 * \sa SDL_BindGPUFragmentSamplers
|
|
|
2795 * \sa SDL_BindGPUFragmentStorageTextures
|
|
|
2796 * \sa SDL_BindGPUComputeStorageTextures
|
|
|
2797 * \sa SDL_BlitGPUTexture
|
|
|
2798 * \sa SDL_ReleaseGPUTexture
|
|
|
2799 * \sa SDL_GPUTextureSupportsFormat
|
|
|
2800 */
|
|
|
2801 extern SDL_DECLSPEC SDL_GPUTexture * SDLCALL SDL_CreateGPUTexture(
|
|
|
2802 SDL_GPUDevice *device,
|
|
|
2803 const SDL_GPUTextureCreateInfo *createinfo);
|
|
|
2804
|
|
|
2805 #define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r"
|
|
|
2806 #define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g"
|
|
|
2807 #define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b"
|
|
|
2808 #define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a"
|
|
|
2809 #define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth"
|
|
|
2810 #define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER "SDL.gpu.texture.create.d3d12.clear.stencil"
|
|
|
2811 #define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name"
|
|
|
2812
|
|
|
2813 /**
|
|
|
2814 * Creates a buffer object to be used in graphics or compute workflows.
|
|
|
2815 *
|
|
|
2816 * The contents of this buffer are undefined until data is written to the
|
|
|
2817 * buffer.
|
|
|
2818 *
|
|
|
2819 * Note that certain combinations of usage flags are invalid. For example, a
|
|
|
2820 * buffer cannot have both the VERTEX and INDEX flags.
|
|
|
2821 *
|
|
|
2822 * If you use a STORAGE flag, the data in the buffer must respect std140
|
|
|
2823 * layout conventions. In practical terms this means you must ensure that vec3
|
|
|
2824 * and vec4 fields are 16-byte aligned.
|
|
|
2825 *
|
|
|
2826 * For better understanding of underlying concepts and memory management with
|
|
|
2827 * SDL GPU API, you may refer
|
|
|
2828 * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/)
|
|
|
2829 * .
|
|
|
2830 *
|
|
|
2831 * There are optional properties that can be provided through `props`. These
|
|
|
2832 * are the supported properties:
|
|
|
2833 *
|
|
|
2834 * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in
|
|
|
2835 * debugging tools.
|
|
|
2836 *
|
|
|
2837 * \param device a GPU Context.
|
|
|
2838 * \param createinfo a struct describing the state of the buffer to create.
|
|
|
2839 * \returns a buffer object on success, or NULL on failure; call
|
|
|
2840 * SDL_GetError() for more information.
|
|
|
2841 *
|
|
|
2842 * \since This function is available since SDL 3.2.0.
|
|
|
2843 *
|
|
|
2844 * \sa SDL_UploadToGPUBuffer
|
|
|
2845 * \sa SDL_DownloadFromGPUBuffer
|
|
|
2846 * \sa SDL_CopyGPUBufferToBuffer
|
|
|
2847 * \sa SDL_BindGPUVertexBuffers
|
|
|
2848 * \sa SDL_BindGPUIndexBuffer
|
|
|
2849 * \sa SDL_BindGPUVertexStorageBuffers
|
|
|
2850 * \sa SDL_BindGPUFragmentStorageBuffers
|
|
|
2851 * \sa SDL_DrawGPUPrimitivesIndirect
|
|
|
2852 * \sa SDL_DrawGPUIndexedPrimitivesIndirect
|
|
|
2853 * \sa SDL_BindGPUComputeStorageBuffers
|
|
|
2854 * \sa SDL_DispatchGPUComputeIndirect
|
|
|
2855 * \sa SDL_ReleaseGPUBuffer
|
|
|
2856 */
|
|
|
2857 extern SDL_DECLSPEC SDL_GPUBuffer * SDLCALL SDL_CreateGPUBuffer(
|
|
|
2858 SDL_GPUDevice *device,
|
|
|
2859 const SDL_GPUBufferCreateInfo *createinfo);
|
|
|
2860
|
|
|
2861 #define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name"
|
|
|
2862
|
|
|
2863 /**
|
|
|
2864 * Creates a transfer buffer to be used when uploading to or downloading from
|
|
|
2865 * graphics resources.
|
|
|
2866 *
|
|
|
2867 * Download buffers can be particularly expensive to create, so it is good
|
|
|
2868 * practice to reuse them if data will be downloaded regularly.
|
|
|
2869 *
|
|
|
2870 * There are optional properties that can be provided through `props`. These
|
|
|
2871 * are the supported properties:
|
|
|
2872 *
|
|
|
2873 * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be
|
|
|
2874 * displayed in debugging tools.
|
|
|
2875 *
|
|
|
2876 * \param device a GPU Context.
|
|
|
2877 * \param createinfo a struct describing the state of the transfer buffer to
|
|
|
2878 * create.
|
|
|
2879 * \returns a transfer buffer on success, or NULL on failure; call
|
|
|
2880 * SDL_GetError() for more information.
|
|
|
2881 *
|
|
|
2882 * \since This function is available since SDL 3.2.0.
|
|
|
2883 *
|
|
|
2884 * \sa SDL_UploadToGPUBuffer
|
|
|
2885 * \sa SDL_DownloadFromGPUBuffer
|
|
|
2886 * \sa SDL_UploadToGPUTexture
|
|
|
2887 * \sa SDL_DownloadFromGPUTexture
|
|
|
2888 * \sa SDL_ReleaseGPUTransferBuffer
|
|
|
2889 */
|
|
|
2890 extern SDL_DECLSPEC SDL_GPUTransferBuffer * SDLCALL SDL_CreateGPUTransferBuffer(
|
|
|
2891 SDL_GPUDevice *device,
|
|
|
2892 const SDL_GPUTransferBufferCreateInfo *createinfo);
|
|
|
2893
|
|
|
2894 #define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name"
|
|
|
2895
|
|
|
2896 /* Debug Naming */
|
|
|
2897
|
|
|
2898 /**
|
|
|
2899 * Sets an arbitrary string constant to label a buffer.
|
|
|
2900 *
|
|
|
2901 * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with
|
|
|
2902 * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues.
|
|
|
2903 *
|
|
|
2904 * \param device a GPU Context.
|
|
|
2905 * \param buffer a buffer to attach the name to.
|
|
|
2906 * \param text a UTF-8 string constant to mark as the name of the buffer.
|
|
|
2907 *
|
|
|
2908 * \threadsafety This function is not thread safe, you must make sure the
|
|
|
2909 * buffer is not simultaneously used by any other thread.
|
|
|
2910 *
|
|
|
2911 * \since This function is available since SDL 3.2.0.
|
|
|
2912 *
|
|
|
2913 * \sa SDL_CreateGPUBuffer
|
|
|
2914 */
|
|
|
2915 extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName(
|
|
|
2916 SDL_GPUDevice *device,
|
|
|
2917 SDL_GPUBuffer *buffer,
|
|
|
2918 const char *text);
|
|
|
2919
|
|
|
2920 /**
|
|
|
2921 * Sets an arbitrary string constant to label a texture.
|
|
|
2922 *
|
|
|
2923 * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with
|
|
|
2924 * SDL_CreateGPUTexture instead of this function to avoid thread safety
|
|
|
2925 * issues.
|
|
|
2926 *
|
|
|
2927 * \param device a GPU Context.
|
|
|
2928 * \param texture a texture to attach the name to.
|
|
|
2929 * \param text a UTF-8 string constant to mark as the name of the texture.
|
|
|
2930 *
|
|
|
2931 * \threadsafety This function is not thread safe, you must make sure the
|
|
|
2932 * texture is not simultaneously used by any other thread.
|
|
|
2933 *
|
|
|
2934 * \since This function is available since SDL 3.2.0.
|
|
|
2935 *
|
|
|
2936 * \sa SDL_CreateGPUTexture
|
|
|
2937 */
|
|
|
2938 extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName(
|
|
|
2939 SDL_GPUDevice *device,
|
|
|
2940 SDL_GPUTexture *texture,
|
|
|
2941 const char *text);
|
|
|
2942
|
|
|
2943 /**
|
|
|
2944 * Inserts an arbitrary string label into the command buffer callstream.
|
|
|
2945 *
|
|
|
2946 * Useful for debugging.
|
|
|
2947 *
|
|
|
2948 * On Direct3D 12, using SDL_InsertGPUDebugLabel requires
|
|
|
2949 * WinPixEventRuntime.dll to be in your PATH or in the same directory as your
|
|
|
2950 * executable. See
|
|
|
2951 * [here](https://devblogs.microsoft.com/pix/winpixeventruntime/)
|
|
|
2952 * for instructions on how to obtain it.
|
|
|
2953 *
|
|
|
2954 * \param command_buffer a command buffer.
|
|
|
2955 * \param text a UTF-8 string constant to insert as the label.
|
|
|
2956 *
|
|
|
2957 * \since This function is available since SDL 3.2.0.
|
|
|
2958 */
|
|
|
2959 extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel(
|
|
|
2960 SDL_GPUCommandBuffer *command_buffer,
|
|
|
2961 const char *text);
|
|
|
2962
|
|
|
2963 /**
|
|
|
2964 * Begins a debug group with an arbitrary name.
|
|
|
2965 *
|
|
|
2966 * Used for denoting groups of calls when viewing the command buffer
|
|
|
2967 * callstream in a graphics debugging tool.
|
|
|
2968 *
|
|
|
2969 * Each call to SDL_PushGPUDebugGroup must have a corresponding call to
|
|
|
2970 * SDL_PopGPUDebugGroup.
|
|
|
2971 *
|
|
|
2972 * On Direct3D 12, using SDL_PushGPUDebugGroup requires WinPixEventRuntime.dll
|
|
|
2973 * to be in your PATH or in the same directory as your executable. See
|
|
|
2974 * [here](https://devblogs.microsoft.com/pix/winpixeventruntime/)
|
|
|
2975 * for instructions on how to obtain it.
|
|
|
2976 *
|
|
|
2977 * On some backends (e.g. Metal), pushing a debug group during a
|
|
|
2978 * render/blit/compute pass will create a group that is scoped to the native
|
|
|
2979 * pass rather than the command buffer. For best results, if you push a debug
|
|
|
2980 * group during a pass, always pop it in the same pass.
|
|
|
2981 *
|
|
|
2982 * \param command_buffer a command buffer.
|
|
|
2983 * \param name a UTF-8 string constant that names the group.
|
|
|
2984 *
|
|
|
2985 * \since This function is available since SDL 3.2.0.
|
|
|
2986 *
|
|
|
2987 * \sa SDL_PopGPUDebugGroup
|
|
|
2988 */
|
|
|
2989 extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup(
|
|
|
2990 SDL_GPUCommandBuffer *command_buffer,
|
|
|
2991 const char *name);
|
|
|
2992
|
|
|
2993 /**
|
|
|
2994 * Ends the most-recently pushed debug group.
|
|
|
2995 *
|
|
|
2996 * On Direct3D 12, using SDL_PopGPUDebugGroup requires WinPixEventRuntime.dll
|
|
|
2997 * to be in your PATH or in the same directory as your executable. See
|
|
|
2998 * [here](https://devblogs.microsoft.com/pix/winpixeventruntime/)
|
|
|
2999 * for instructions on how to obtain it.
|
|
|
3000 *
|
|
|
3001 * \param command_buffer a command buffer.
|
|
|
3002 *
|
|
|
3003 * \since This function is available since SDL 3.2.0.
|
|
|
3004 *
|
|
|
3005 * \sa SDL_PushGPUDebugGroup
|
|
|
3006 */
|
|
|
3007 extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup(
|
|
|
3008 SDL_GPUCommandBuffer *command_buffer);
|
|
|
3009
|
|
|
3010 /* Disposal */
|
|
|
3011
|
|
|
3012 /**
|
|
|
3013 * Frees the given texture as soon as it is safe to do so.
|
|
|
3014 *
|
|
|
3015 * You must not reference the texture after calling this function.
|
|
|
3016 *
|
|
|
3017 * \param device a GPU context.
|
|
|
3018 * \param texture a texture to be destroyed.
|
|
|
3019 *
|
|
|
3020 * \since This function is available since SDL 3.2.0.
|
|
|
3021 */
|
|
|
3022 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture(
|
|
|
3023 SDL_GPUDevice *device,
|
|
|
3024 SDL_GPUTexture *texture);
|
|
|
3025
|
|
|
3026 /**
|
|
|
3027 * Frees the given sampler as soon as it is safe to do so.
|
|
|
3028 *
|
|
|
3029 * You must not reference the sampler after calling this function.
|
|
|
3030 *
|
|
|
3031 * \param device a GPU context.
|
|
|
3032 * \param sampler a sampler to be destroyed.
|
|
|
3033 *
|
|
|
3034 * \since This function is available since SDL 3.2.0.
|
|
|
3035 */
|
|
|
3036 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler(
|
|
|
3037 SDL_GPUDevice *device,
|
|
|
3038 SDL_GPUSampler *sampler);
|
|
|
3039
|
|
|
3040 /**
|
|
|
3041 * Frees the given buffer as soon as it is safe to do so.
|
|
|
3042 *
|
|
|
3043 * You must not reference the buffer after calling this function.
|
|
|
3044 *
|
|
|
3045 * \param device a GPU context.
|
|
|
3046 * \param buffer a buffer to be destroyed.
|
|
|
3047 *
|
|
|
3048 * \since This function is available since SDL 3.2.0.
|
|
|
3049 */
|
|
|
3050 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer(
|
|
|
3051 SDL_GPUDevice *device,
|
|
|
3052 SDL_GPUBuffer *buffer);
|
|
|
3053
|
|
|
3054 /**
|
|
|
3055 * Frees the given transfer buffer as soon as it is safe to do so.
|
|
|
3056 *
|
|
|
3057 * You must not reference the transfer buffer after calling this function.
|
|
|
3058 *
|
|
|
3059 * \param device a GPU context.
|
|
|
3060 * \param transfer_buffer a transfer buffer to be destroyed.
|
|
|
3061 *
|
|
|
3062 * \since This function is available since SDL 3.2.0.
|
|
|
3063 */
|
|
|
3064 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer(
|
|
|
3065 SDL_GPUDevice *device,
|
|
|
3066 SDL_GPUTransferBuffer *transfer_buffer);
|
|
|
3067
|
|
|
3068 /**
|
|
|
3069 * Frees the given compute pipeline as soon as it is safe to do so.
|
|
|
3070 *
|
|
|
3071 * You must not reference the compute pipeline after calling this function.
|
|
|
3072 *
|
|
|
3073 * \param device a GPU context.
|
|
|
3074 * \param compute_pipeline a compute pipeline to be destroyed.
|
|
|
3075 *
|
|
|
3076 * \since This function is available since SDL 3.2.0.
|
|
|
3077 */
|
|
|
3078 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline(
|
|
|
3079 SDL_GPUDevice *device,
|
|
|
3080 SDL_GPUComputePipeline *compute_pipeline);
|
|
|
3081
|
|
|
3082 /**
|
|
|
3083 * Frees the given shader as soon as it is safe to do so.
|
|
|
3084 *
|
|
|
3085 * You must not reference the shader after calling this function.
|
|
|
3086 *
|
|
|
3087 * \param device a GPU context.
|
|
|
3088 * \param shader a shader to be destroyed.
|
|
|
3089 *
|
|
|
3090 * \since This function is available since SDL 3.2.0.
|
|
|
3091 */
|
|
|
3092 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader(
|
|
|
3093 SDL_GPUDevice *device,
|
|
|
3094 SDL_GPUShader *shader);
|
|
|
3095
|
|
|
3096 /**
|
|
|
3097 * Frees the given graphics pipeline as soon as it is safe to do so.
|
|
|
3098 *
|
|
|
3099 * You must not reference the graphics pipeline after calling this function.
|
|
|
3100 *
|
|
|
3101 * \param device a GPU context.
|
|
|
3102 * \param graphics_pipeline a graphics pipeline to be destroyed.
|
|
|
3103 *
|
|
|
3104 * \since This function is available since SDL 3.2.0.
|
|
|
3105 */
|
|
|
3106 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline(
|
|
|
3107 SDL_GPUDevice *device,
|
|
|
3108 SDL_GPUGraphicsPipeline *graphics_pipeline);
|
|
|
3109
|
|
|
3110 /**
|
|
|
3111 * Acquire a command buffer.
|
|
|
3112 *
|
|
|
3113 * This command buffer is managed by the implementation and should not be
|
|
|
3114 * freed by the user. The command buffer may only be used on the thread it was
|
|
|
3115 * acquired on. The command buffer should be submitted on the thread it was
|
|
|
3116 * acquired on.
|
|
|
3117 *
|
|
|
3118 * It is valid to acquire multiple command buffers on the same thread at once.
|
|
|
3119 * In fact a common design pattern is to acquire two command buffers per frame
|
|
|
3120 * where one is dedicated to render and compute passes and the other is
|
|
|
3121 * dedicated to copy passes and other preparatory work such as generating
|
|
|
3122 * mipmaps. Interleaving commands between the two command buffers reduces the
|
|
|
3123 * total amount of passes overall which improves rendering performance.
|
|
|
3124 *
|
|
|
3125 * \param device a GPU context.
|
|
|
3126 * \returns a command buffer, or NULL on failure; call SDL_GetError() for more
|
|
|
3127 * information.
|
|
|
3128 *
|
|
|
3129 * \since This function is available since SDL 3.2.0.
|
|
|
3130 *
|
|
|
3131 * \sa SDL_SubmitGPUCommandBuffer
|
|
|
3132 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
3133 */
|
|
|
3134 extern SDL_DECLSPEC SDL_GPUCommandBuffer * SDLCALL SDL_AcquireGPUCommandBuffer(
|
|
|
3135 SDL_GPUDevice *device);
|
|
|
3136
|
|
|
3137 /* Uniform Data */
|
|
|
3138
|
|
|
3139 /**
|
|
|
3140 * Pushes data to a vertex uniform slot on the command buffer.
|
|
|
3141 *
|
|
|
3142 * Subsequent draw calls in this command buffer will use this uniform data.
|
|
|
3143 *
|
|
|
3144 * The data being pushed must respect std140 layout conventions. In practical
|
|
|
3145 * terms this means you must ensure that vec3 and vec4 fields are 16-byte
|
|
|
3146 * aligned.
|
|
|
3147 *
|
|
|
3148 * For detailed information about accessing uniform data from a shader, please
|
|
|
3149 * refer to SDL_CreateGPUShader.
|
|
|
3150 *
|
|
|
3151 * \param command_buffer a command buffer.
|
|
|
3152 * \param slot_index the vertex uniform slot to push data to.
|
|
|
3153 * \param data client data to write.
|
|
|
3154 * \param length the length of the data to write.
|
|
|
3155 *
|
|
|
3156 * \since This function is available since SDL 3.2.0.
|
|
|
3157 */
|
|
|
3158 extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData(
|
|
|
3159 SDL_GPUCommandBuffer *command_buffer,
|
|
|
3160 Uint32 slot_index,
|
|
|
3161 const void *data,
|
|
|
3162 Uint32 length);
|
|
|
3163
|
|
|
3164 /**
|
|
|
3165 * Pushes data to a fragment uniform slot on the command buffer.
|
|
|
3166 *
|
|
|
3167 * Subsequent draw calls in this command buffer will use this uniform data.
|
|
|
3168 *
|
|
|
3169 * The data being pushed must respect std140 layout conventions. In practical
|
|
|
3170 * terms this means you must ensure that vec3 and vec4 fields are 16-byte
|
|
|
3171 * aligned.
|
|
|
3172 *
|
|
|
3173 * \param command_buffer a command buffer.
|
|
|
3174 * \param slot_index the fragment uniform slot to push data to.
|
|
|
3175 * \param data client data to write.
|
|
|
3176 * \param length the length of the data to write.
|
|
|
3177 *
|
|
|
3178 * \since This function is available since SDL 3.2.0.
|
|
|
3179 */
|
|
|
3180 extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData(
|
|
|
3181 SDL_GPUCommandBuffer *command_buffer,
|
|
|
3182 Uint32 slot_index,
|
|
|
3183 const void *data,
|
|
|
3184 Uint32 length);
|
|
|
3185
|
|
|
3186 /**
|
|
|
3187 * Pushes data to a uniform slot on the command buffer.
|
|
|
3188 *
|
|
|
3189 * Subsequent draw calls in this command buffer will use this uniform data.
|
|
|
3190 *
|
|
|
3191 * The data being pushed must respect std140 layout conventions. In practical
|
|
|
3192 * terms this means you must ensure that vec3 and vec4 fields are 16-byte
|
|
|
3193 * aligned.
|
|
|
3194 *
|
|
|
3195 * \param command_buffer a command buffer.
|
|
|
3196 * \param slot_index the uniform slot to push data to.
|
|
|
3197 * \param data client data to write.
|
|
|
3198 * \param length the length of the data to write.
|
|
|
3199 *
|
|
|
3200 * \since This function is available since SDL 3.2.0.
|
|
|
3201 */
|
|
|
3202 extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData(
|
|
|
3203 SDL_GPUCommandBuffer *command_buffer,
|
|
|
3204 Uint32 slot_index,
|
|
|
3205 const void *data,
|
|
|
3206 Uint32 length);
|
|
|
3207
|
|
|
3208 /* Graphics State */
|
|
|
3209
|
|
|
3210 /**
|
|
|
3211 * Begins a render pass on a command buffer.
|
|
|
3212 *
|
|
|
3213 * A render pass consists of a set of texture subresources (or depth slices in
|
|
|
3214 * the 3D texture case) which will be rendered to during the render pass,
|
|
|
3215 * along with corresponding clear values and load/store operations. All
|
|
|
3216 * operations related to graphics pipelines must take place inside of a render
|
|
|
3217 * pass. A default viewport and scissor state are automatically set when this
|
|
|
3218 * is called. You cannot begin another render pass, or begin a compute pass or
|
|
|
3219 * copy pass until you have ended the render pass.
|
|
|
3220 *
|
|
|
3221 * Using SDL_GPU_LOADOP_LOAD before any contents have been written to the
|
|
|
3222 * texture subresource will result in undefined behavior. SDL_GPU_LOADOP_CLEAR
|
|
|
3223 * will set the contents of the texture subresource to a single value before
|
|
|
3224 * any rendering is performed. It's fine to do an empty render pass using
|
|
|
3225 * SDL_GPU_STOREOP_STORE to clear a texture, but in general it's better to
|
|
|
3226 * think of clearing not as an independent operation but as something that's
|
|
|
3227 * done as the beginning of a render pass.
|
|
|
3228 *
|
|
|
3229 * \param command_buffer a command buffer.
|
|
|
3230 * \param color_target_infos an array of texture subresources with
|
|
|
3231 * corresponding clear values and load/store ops.
|
|
|
3232 * \param num_color_targets the number of color targets in the
|
|
|
3233 * color_target_infos array.
|
|
|
3234 * \param depth_stencil_target_info a texture subresource with corresponding
|
|
|
3235 * clear value and load/store ops, may be
|
|
|
3236 * NULL.
|
|
|
3237 * \returns a render pass handle.
|
|
|
3238 *
|
|
|
3239 * \since This function is available since SDL 3.2.0.
|
|
|
3240 *
|
|
|
3241 * \sa SDL_EndGPURenderPass
|
|
|
3242 */
|
|
|
3243 extern SDL_DECLSPEC SDL_GPURenderPass * SDLCALL SDL_BeginGPURenderPass(
|
|
|
3244 SDL_GPUCommandBuffer *command_buffer,
|
|
|
3245 const SDL_GPUColorTargetInfo *color_target_infos,
|
|
|
3246 Uint32 num_color_targets,
|
|
|
3247 const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info);
|
|
|
3248
|
|
|
3249 /**
|
|
|
3250 * Binds a graphics pipeline on a render pass to be used in rendering.
|
|
|
3251 *
|
|
|
3252 * A graphics pipeline must be bound before making any draw calls.
|
|
|
3253 *
|
|
|
3254 * \param render_pass a render pass handle.
|
|
|
3255 * \param graphics_pipeline the graphics pipeline to bind.
|
|
|
3256 *
|
|
|
3257 * \since This function is available since SDL 3.2.0.
|
|
|
3258 */
|
|
|
3259 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline(
|
|
|
3260 SDL_GPURenderPass *render_pass,
|
|
|
3261 SDL_GPUGraphicsPipeline *graphics_pipeline);
|
|
|
3262
|
|
|
3263 /**
|
|
|
3264 * Sets the current viewport state on a command buffer.
|
|
|
3265 *
|
|
|
3266 * \param render_pass a render pass handle.
|
|
|
3267 * \param viewport the viewport to set.
|
|
|
3268 *
|
|
|
3269 * \since This function is available since SDL 3.2.0.
|
|
|
3270 */
|
|
|
3271 extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport(
|
|
|
3272 SDL_GPURenderPass *render_pass,
|
|
|
3273 const SDL_GPUViewport *viewport);
|
|
|
3274
|
|
|
3275 /**
|
|
|
3276 * Sets the current scissor state on a command buffer.
|
|
|
3277 *
|
|
|
3278 * \param render_pass a render pass handle.
|
|
|
3279 * \param scissor the scissor area to set.
|
|
|
3280 *
|
|
|
3281 * \since This function is available since SDL 3.2.0.
|
|
|
3282 */
|
|
|
3283 extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor(
|
|
|
3284 SDL_GPURenderPass *render_pass,
|
|
|
3285 const SDL_Rect *scissor);
|
|
|
3286
|
|
|
3287 /**
|
|
|
3288 * Sets the current blend constants on a command buffer.
|
|
|
3289 *
|
|
|
3290 * \param render_pass a render pass handle.
|
|
|
3291 * \param blend_constants the blend constant color.
|
|
|
3292 *
|
|
|
3293 * \since This function is available since SDL 3.2.0.
|
|
|
3294 *
|
|
|
3295 * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR
|
|
|
3296 * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR
|
|
|
3297 */
|
|
|
3298 extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants(
|
|
|
3299 SDL_GPURenderPass *render_pass,
|
|
|
3300 SDL_FColor blend_constants);
|
|
|
3301
|
|
|
3302 /**
|
|
|
3303 * Sets the current stencil reference value on a command buffer.
|
|
|
3304 *
|
|
|
3305 * \param render_pass a render pass handle.
|
|
|
3306 * \param reference the stencil reference value to set.
|
|
|
3307 *
|
|
|
3308 * \since This function is available since SDL 3.2.0.
|
|
|
3309 */
|
|
|
3310 extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference(
|
|
|
3311 SDL_GPURenderPass *render_pass,
|
|
|
3312 Uint8 reference);
|
|
|
3313
|
|
|
3314 /**
|
|
|
3315 * Binds vertex buffers on a command buffer for use with subsequent draw
|
|
|
3316 * calls.
|
|
|
3317 *
|
|
|
3318 * \param render_pass a render pass handle.
|
|
|
3319 * \param first_slot the vertex buffer slot to begin binding from.
|
|
|
3320 * \param bindings an array of SDL_GPUBufferBinding structs containing vertex
|
|
|
3321 * buffers and offset values.
|
|
|
3322 * \param num_bindings the number of bindings in the bindings array.
|
|
|
3323 *
|
|
|
3324 * \since This function is available since SDL 3.2.0.
|
|
|
3325 */
|
|
|
3326 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers(
|
|
|
3327 SDL_GPURenderPass *render_pass,
|
|
|
3328 Uint32 first_slot,
|
|
|
3329 const SDL_GPUBufferBinding *bindings,
|
|
|
3330 Uint32 num_bindings);
|
|
|
3331
|
|
|
3332 /**
|
|
|
3333 * Binds an index buffer on a command buffer for use with subsequent draw
|
|
|
3334 * calls.
|
|
|
3335 *
|
|
|
3336 * \param render_pass a render pass handle.
|
|
|
3337 * \param binding a pointer to a struct containing an index buffer and offset.
|
|
|
3338 * \param index_element_size whether the index values in the buffer are 16- or
|
|
|
3339 * 32-bit.
|
|
|
3340 *
|
|
|
3341 * \since This function is available since SDL 3.2.0.
|
|
|
3342 */
|
|
|
3343 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer(
|
|
|
3344 SDL_GPURenderPass *render_pass,
|
|
|
3345 const SDL_GPUBufferBinding *binding,
|
|
|
3346 SDL_GPUIndexElementSize index_element_size);
|
|
|
3347
|
|
|
3348 /**
|
|
|
3349 * Binds texture-sampler pairs for use on the vertex shader.
|
|
|
3350 *
|
|
|
3351 * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
|
|
|
3352 *
|
|
|
3353 * Be sure your shader is set up according to the requirements documented in
|
|
|
3354 * SDL_CreateGPUShader().
|
|
|
3355 *
|
|
|
3356 * \param render_pass a render pass handle.
|
|
|
3357 * \param first_slot the vertex sampler slot to begin binding from.
|
|
|
3358 * \param texture_sampler_bindings an array of texture-sampler binding
|
|
|
3359 * structs.
|
|
|
3360 * \param num_bindings the number of texture-sampler pairs to bind from the
|
|
|
3361 * array.
|
|
|
3362 *
|
|
|
3363 * \since This function is available since SDL 3.2.0.
|
|
|
3364 *
|
|
|
3365 * \sa SDL_CreateGPUShader
|
|
|
3366 */
|
|
|
3367 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers(
|
|
|
3368 SDL_GPURenderPass *render_pass,
|
|
|
3369 Uint32 first_slot,
|
|
|
3370 const SDL_GPUTextureSamplerBinding *texture_sampler_bindings,
|
|
|
3371 Uint32 num_bindings);
|
|
|
3372
|
|
|
3373 /**
|
|
|
3374 * Binds storage textures for use on the vertex shader.
|
|
|
3375 *
|
|
|
3376 * These textures must have been created with
|
|
|
3377 * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
|
|
|
3378 *
|
|
|
3379 * Be sure your shader is set up according to the requirements documented in
|
|
|
3380 * SDL_CreateGPUShader().
|
|
|
3381 *
|
|
|
3382 * \param render_pass a render pass handle.
|
|
|
3383 * \param first_slot the vertex storage texture slot to begin binding from.
|
|
|
3384 * \param storage_textures an array of storage textures.
|
|
|
3385 * \param num_bindings the number of storage texture to bind from the array.
|
|
|
3386 *
|
|
|
3387 * \since This function is available since SDL 3.2.0.
|
|
|
3388 *
|
|
|
3389 * \sa SDL_CreateGPUShader
|
|
|
3390 */
|
|
|
3391 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures(
|
|
|
3392 SDL_GPURenderPass *render_pass,
|
|
|
3393 Uint32 first_slot,
|
|
|
3394 SDL_GPUTexture *const *storage_textures,
|
|
|
3395 Uint32 num_bindings);
|
|
|
3396
|
|
|
3397 /**
|
|
|
3398 * Binds storage buffers for use on the vertex shader.
|
|
|
3399 *
|
|
|
3400 * These buffers must have been created with
|
|
|
3401 * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
|
|
|
3402 *
|
|
|
3403 * Be sure your shader is set up according to the requirements documented in
|
|
|
3404 * SDL_CreateGPUShader().
|
|
|
3405 *
|
|
|
3406 * \param render_pass a render pass handle.
|
|
|
3407 * \param first_slot the vertex storage buffer slot to begin binding from.
|
|
|
3408 * \param storage_buffers an array of buffers.
|
|
|
3409 * \param num_bindings the number of buffers to bind from the array.
|
|
|
3410 *
|
|
|
3411 * \since This function is available since SDL 3.2.0.
|
|
|
3412 *
|
|
|
3413 * \sa SDL_CreateGPUShader
|
|
|
3414 */
|
|
|
3415 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers(
|
|
|
3416 SDL_GPURenderPass *render_pass,
|
|
|
3417 Uint32 first_slot,
|
|
|
3418 SDL_GPUBuffer *const *storage_buffers,
|
|
|
3419 Uint32 num_bindings);
|
|
|
3420
|
|
|
3421 /**
|
|
|
3422 * Binds texture-sampler pairs for use on the fragment shader.
|
|
|
3423 *
|
|
|
3424 * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
|
|
|
3425 *
|
|
|
3426 * Be sure your shader is set up according to the requirements documented in
|
|
|
3427 * SDL_CreateGPUShader().
|
|
|
3428 *
|
|
|
3429 * \param render_pass a render pass handle.
|
|
|
3430 * \param first_slot the fragment sampler slot to begin binding from.
|
|
|
3431 * \param texture_sampler_bindings an array of texture-sampler binding
|
|
|
3432 * structs.
|
|
|
3433 * \param num_bindings the number of texture-sampler pairs to bind from the
|
|
|
3434 * array.
|
|
|
3435 *
|
|
|
3436 * \since This function is available since SDL 3.2.0.
|
|
|
3437 *
|
|
|
3438 * \sa SDL_CreateGPUShader
|
|
|
3439 */
|
|
|
3440 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers(
|
|
|
3441 SDL_GPURenderPass *render_pass,
|
|
|
3442 Uint32 first_slot,
|
|
|
3443 const SDL_GPUTextureSamplerBinding *texture_sampler_bindings,
|
|
|
3444 Uint32 num_bindings);
|
|
|
3445
|
|
|
3446 /**
|
|
|
3447 * Binds storage textures for use on the fragment shader.
|
|
|
3448 *
|
|
|
3449 * These textures must have been created with
|
|
|
3450 * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
|
|
|
3451 *
|
|
|
3452 * Be sure your shader is set up according to the requirements documented in
|
|
|
3453 * SDL_CreateGPUShader().
|
|
|
3454 *
|
|
|
3455 * \param render_pass a render pass handle.
|
|
|
3456 * \param first_slot the fragment storage texture slot to begin binding from.
|
|
|
3457 * \param storage_textures an array of storage textures.
|
|
|
3458 * \param num_bindings the number of storage textures to bind from the array.
|
|
|
3459 *
|
|
|
3460 * \since This function is available since SDL 3.2.0.
|
|
|
3461 *
|
|
|
3462 * \sa SDL_CreateGPUShader
|
|
|
3463 */
|
|
|
3464 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures(
|
|
|
3465 SDL_GPURenderPass *render_pass,
|
|
|
3466 Uint32 first_slot,
|
|
|
3467 SDL_GPUTexture *const *storage_textures,
|
|
|
3468 Uint32 num_bindings);
|
|
|
3469
|
|
|
3470 /**
|
|
|
3471 * Binds storage buffers for use on the fragment shader.
|
|
|
3472 *
|
|
|
3473 * These buffers must have been created with
|
|
|
3474 * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
|
|
|
3475 *
|
|
|
3476 * Be sure your shader is set up according to the requirements documented in
|
|
|
3477 * SDL_CreateGPUShader().
|
|
|
3478 *
|
|
|
3479 * \param render_pass a render pass handle.
|
|
|
3480 * \param first_slot the fragment storage buffer slot to begin binding from.
|
|
|
3481 * \param storage_buffers an array of storage buffers.
|
|
|
3482 * \param num_bindings the number of storage buffers to bind from the array.
|
|
|
3483 *
|
|
|
3484 * \since This function is available since SDL 3.2.0.
|
|
|
3485 *
|
|
|
3486 * \sa SDL_CreateGPUShader
|
|
|
3487 */
|
|
|
3488 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers(
|
|
|
3489 SDL_GPURenderPass *render_pass,
|
|
|
3490 Uint32 first_slot,
|
|
|
3491 SDL_GPUBuffer *const *storage_buffers,
|
|
|
3492 Uint32 num_bindings);
|
|
|
3493
|
|
|
3494 /* Drawing */
|
|
|
3495
|
|
|
3496 /**
|
|
|
3497 * Draws data using bound graphics state with an index buffer and instancing
|
|
|
3498 * enabled.
|
|
|
3499 *
|
|
|
3500 * You must not call this function before binding a graphics pipeline.
|
|
|
3501 *
|
|
|
3502 * Note that the `first_vertex` and `first_instance` parameters are NOT
|
|
|
3503 * compatible with built-in vertex/instance ID variables in shaders (for
|
|
|
3504 * example, SV_VertexID); GPU APIs and shader languages do not define these
|
|
|
3505 * built-in variables consistently, so if your shader depends on them, the
|
|
|
3506 * only way to keep behavior consistent and portable is to always pass 0 for
|
|
|
3507 * the correlating parameter in the draw calls.
|
|
|
3508 *
|
|
|
3509 * \param render_pass a render pass handle.
|
|
|
3510 * \param num_indices the number of indices to draw per instance.
|
|
|
3511 * \param num_instances the number of instances to draw.
|
|
|
3512 * \param first_index the starting index within the index buffer.
|
|
|
3513 * \param vertex_offset value added to vertex index before indexing into the
|
|
|
3514 * vertex buffer.
|
|
|
3515 * \param first_instance the ID of the first instance to draw.
|
|
|
3516 *
|
|
|
3517 * \since This function is available since SDL 3.2.0.
|
|
|
3518 */
|
|
|
3519 extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives(
|
|
|
3520 SDL_GPURenderPass *render_pass,
|
|
|
3521 Uint32 num_indices,
|
|
|
3522 Uint32 num_instances,
|
|
|
3523 Uint32 first_index,
|
|
|
3524 Sint32 vertex_offset,
|
|
|
3525 Uint32 first_instance);
|
|
|
3526
|
|
|
3527 /**
|
|
|
3528 * Draws data using bound graphics state.
|
|
|
3529 *
|
|
|
3530 * You must not call this function before binding a graphics pipeline.
|
|
|
3531 *
|
|
|
3532 * Note that the `first_vertex` and `first_instance` parameters are NOT
|
|
|
3533 * compatible with built-in vertex/instance ID variables in shaders (for
|
|
|
3534 * example, SV_VertexID); GPU APIs and shader languages do not define these
|
|
|
3535 * built-in variables consistently, so if your shader depends on them, the
|
|
|
3536 * only way to keep behavior consistent and portable is to always pass 0 for
|
|
|
3537 * the correlating parameter in the draw calls.
|
|
|
3538 *
|
|
|
3539 * \param render_pass a render pass handle.
|
|
|
3540 * \param num_vertices the number of vertices to draw.
|
|
|
3541 * \param num_instances the number of instances that will be drawn.
|
|
|
3542 * \param first_vertex the index of the first vertex to draw.
|
|
|
3543 * \param first_instance the ID of the first instance to draw.
|
|
|
3544 *
|
|
|
3545 * \since This function is available since SDL 3.2.0.
|
|
|
3546 */
|
|
|
3547 extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives(
|
|
|
3548 SDL_GPURenderPass *render_pass,
|
|
|
3549 Uint32 num_vertices,
|
|
|
3550 Uint32 num_instances,
|
|
|
3551 Uint32 first_vertex,
|
|
|
3552 Uint32 first_instance);
|
|
|
3553
|
|
|
3554 /**
|
|
|
3555 * Draws data using bound graphics state and with draw parameters set from a
|
|
|
3556 * buffer.
|
|
|
3557 *
|
|
|
3558 * The buffer must consist of tightly-packed draw parameter sets that each
|
|
|
3559 * match the layout of SDL_GPUIndirectDrawCommand. You must not call this
|
|
|
3560 * function before binding a graphics pipeline.
|
|
|
3561 *
|
|
|
3562 * \param render_pass a render pass handle.
|
|
|
3563 * \param buffer a buffer containing draw parameters.
|
|
|
3564 * \param offset the offset to start reading from the draw buffer.
|
|
|
3565 * \param draw_count the number of draw parameter sets that should be read
|
|
|
3566 * from the draw buffer.
|
|
|
3567 *
|
|
|
3568 * \since This function is available since SDL 3.2.0.
|
|
|
3569 */
|
|
|
3570 extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect(
|
|
|
3571 SDL_GPURenderPass *render_pass,
|
|
|
3572 SDL_GPUBuffer *buffer,
|
|
|
3573 Uint32 offset,
|
|
|
3574 Uint32 draw_count);
|
|
|
3575
|
|
|
3576 /**
|
|
|
3577 * Draws data using bound graphics state with an index buffer enabled and with
|
|
|
3578 * draw parameters set from a buffer.
|
|
|
3579 *
|
|
|
3580 * The buffer must consist of tightly-packed draw parameter sets that each
|
|
|
3581 * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call
|
|
|
3582 * this function before binding a graphics pipeline.
|
|
|
3583 *
|
|
|
3584 * \param render_pass a render pass handle.
|
|
|
3585 * \param buffer a buffer containing draw parameters.
|
|
|
3586 * \param offset the offset to start reading from the draw buffer.
|
|
|
3587 * \param draw_count the number of draw parameter sets that should be read
|
|
|
3588 * from the draw buffer.
|
|
|
3589 *
|
|
|
3590 * \since This function is available since SDL 3.2.0.
|
|
|
3591 */
|
|
|
3592 extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect(
|
|
|
3593 SDL_GPURenderPass *render_pass,
|
|
|
3594 SDL_GPUBuffer *buffer,
|
|
|
3595 Uint32 offset,
|
|
|
3596 Uint32 draw_count);
|
|
|
3597
|
|
|
3598 /**
|
|
|
3599 * Ends the given render pass.
|
|
|
3600 *
|
|
|
3601 * All bound graphics state on the render pass command buffer is unset. The
|
|
|
3602 * render pass handle is now invalid.
|
|
|
3603 *
|
|
|
3604 * \param render_pass a render pass handle.
|
|
|
3605 *
|
|
|
3606 * \since This function is available since SDL 3.2.0.
|
|
|
3607 */
|
|
|
3608 extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass(
|
|
|
3609 SDL_GPURenderPass *render_pass);
|
|
|
3610
|
|
|
3611 /* Compute Pass */
|
|
|
3612
|
|
|
3613 /**
|
|
|
3614 * Begins a compute pass on a command buffer.
|
|
|
3615 *
|
|
|
3616 * A compute pass is defined by a set of texture subresources and buffers that
|
|
|
3617 * may be written to by compute pipelines. These textures and buffers must
|
|
|
3618 * have been created with the COMPUTE_STORAGE_WRITE bit or the
|
|
|
3619 * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture
|
|
|
3620 * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the
|
|
|
3621 * texture in the compute pass. All operations related to compute pipelines
|
|
|
3622 * must take place inside of a compute pass. You must not begin another
|
|
|
3623 * compute pass, or a render pass or copy pass before ending the compute pass.
|
|
|
3624 *
|
|
|
3625 * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT
|
|
|
3626 * implicitly synchronized. This means you may cause data races by both
|
|
|
3627 * reading and writing a resource region in a compute pass, or by writing
|
|
|
3628 * multiple times to a resource region. If your compute work depends on
|
|
|
3629 * reading the completed output from a previous dispatch, you MUST end the
|
|
|
3630 * current compute pass and begin a new one before you can safely access the
|
|
|
3631 * data. Otherwise you will receive unexpected results. Reading and writing a
|
|
|
3632 * texture in the same compute pass is only supported by specific texture
|
|
|
3633 * formats. Make sure you check the format support!
|
|
|
3634 *
|
|
|
3635 * \param command_buffer a command buffer.
|
|
|
3636 * \param storage_texture_bindings an array of writeable storage texture
|
|
|
3637 * binding structs.
|
|
|
3638 * \param num_storage_texture_bindings the number of storage textures to bind
|
|
|
3639 * from the array.
|
|
|
3640 * \param storage_buffer_bindings an array of writeable storage buffer binding
|
|
|
3641 * structs.
|
|
|
3642 * \param num_storage_buffer_bindings the number of storage buffers to bind
|
|
|
3643 * from the array.
|
|
|
3644 * \returns a compute pass handle.
|
|
|
3645 *
|
|
|
3646 * \since This function is available since SDL 3.2.0.
|
|
|
3647 *
|
|
|
3648 * \sa SDL_EndGPUComputePass
|
|
|
3649 */
|
|
|
3650 extern SDL_DECLSPEC SDL_GPUComputePass * SDLCALL SDL_BeginGPUComputePass(
|
|
|
3651 SDL_GPUCommandBuffer *command_buffer,
|
|
|
3652 const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings,
|
|
|
3653 Uint32 num_storage_texture_bindings,
|
|
|
3654 const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings,
|
|
|
3655 Uint32 num_storage_buffer_bindings);
|
|
|
3656
|
|
|
3657 /**
|
|
|
3658 * Binds a compute pipeline on a command buffer for use in compute dispatch.
|
|
|
3659 *
|
|
|
3660 * \param compute_pass a compute pass handle.
|
|
|
3661 * \param compute_pipeline a compute pipeline to bind.
|
|
|
3662 *
|
|
|
3663 * \since This function is available since SDL 3.2.0.
|
|
|
3664 */
|
|
|
3665 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline(
|
|
|
3666 SDL_GPUComputePass *compute_pass,
|
|
|
3667 SDL_GPUComputePipeline *compute_pipeline);
|
|
|
3668
|
|
|
3669 /**
|
|
|
3670 * Binds texture-sampler pairs for use on the compute shader.
|
|
|
3671 *
|
|
|
3672 * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
|
|
|
3673 *
|
|
|
3674 * Be sure your shader is set up according to the requirements documented in
|
|
|
3675 * SDL_CreateGPUComputePipeline().
|
|
|
3676 *
|
|
|
3677 * \param compute_pass a compute pass handle.
|
|
|
3678 * \param first_slot the compute sampler slot to begin binding from.
|
|
|
3679 * \param texture_sampler_bindings an array of texture-sampler binding
|
|
|
3680 * structs.
|
|
|
3681 * \param num_bindings the number of texture-sampler bindings to bind from the
|
|
|
3682 * array.
|
|
|
3683 *
|
|
|
3684 * \since This function is available since SDL 3.2.0.
|
|
|
3685 *
|
|
|
3686 * \sa SDL_CreateGPUComputePipeline
|
|
|
3687 */
|
|
|
3688 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers(
|
|
|
3689 SDL_GPUComputePass *compute_pass,
|
|
|
3690 Uint32 first_slot,
|
|
|
3691 const SDL_GPUTextureSamplerBinding *texture_sampler_bindings,
|
|
|
3692 Uint32 num_bindings);
|
|
|
3693
|
|
|
3694 /**
|
|
|
3695 * Binds storage textures as readonly for use on the compute pipeline.
|
|
|
3696 *
|
|
|
3697 * These textures must have been created with
|
|
|
3698 * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.
|
|
|
3699 *
|
|
|
3700 * Be sure your shader is set up according to the requirements documented in
|
|
|
3701 * SDL_CreateGPUComputePipeline().
|
|
|
3702 *
|
|
|
3703 * \param compute_pass a compute pass handle.
|
|
|
3704 * \param first_slot the compute storage texture slot to begin binding from.
|
|
|
3705 * \param storage_textures an array of storage textures.
|
|
|
3706 * \param num_bindings the number of storage textures to bind from the array.
|
|
|
3707 *
|
|
|
3708 * \since This function is available since SDL 3.2.0.
|
|
|
3709 *
|
|
|
3710 * \sa SDL_CreateGPUComputePipeline
|
|
|
3711 */
|
|
|
3712 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures(
|
|
|
3713 SDL_GPUComputePass *compute_pass,
|
|
|
3714 Uint32 first_slot,
|
|
|
3715 SDL_GPUTexture *const *storage_textures,
|
|
|
3716 Uint32 num_bindings);
|
|
|
3717
|
|
|
3718 /**
|
|
|
3719 * Binds storage buffers as readonly for use on the compute pipeline.
|
|
|
3720 *
|
|
|
3721 * These buffers must have been created with
|
|
|
3722 * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ.
|
|
|
3723 *
|
|
|
3724 * Be sure your shader is set up according to the requirements documented in
|
|
|
3725 * SDL_CreateGPUComputePipeline().
|
|
|
3726 *
|
|
|
3727 * \param compute_pass a compute pass handle.
|
|
|
3728 * \param first_slot the compute storage buffer slot to begin binding from.
|
|
|
3729 * \param storage_buffers an array of storage buffer binding structs.
|
|
|
3730 * \param num_bindings the number of storage buffers to bind from the array.
|
|
|
3731 *
|
|
|
3732 * \since This function is available since SDL 3.2.0.
|
|
|
3733 *
|
|
|
3734 * \sa SDL_CreateGPUComputePipeline
|
|
|
3735 */
|
|
|
3736 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers(
|
|
|
3737 SDL_GPUComputePass *compute_pass,
|
|
|
3738 Uint32 first_slot,
|
|
|
3739 SDL_GPUBuffer *const *storage_buffers,
|
|
|
3740 Uint32 num_bindings);
|
|
|
3741
|
|
|
3742 /**
|
|
|
3743 * Dispatches compute work.
|
|
|
3744 *
|
|
|
3745 * You must not call this function before binding a compute pipeline.
|
|
|
3746 *
|
|
|
3747 * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and
|
|
|
3748 * the dispatches write to the same resource region as each other, there is no
|
|
|
3749 * guarantee of which order the writes will occur. If the write order matters,
|
|
|
3750 * you MUST end the compute pass and begin another one.
|
|
|
3751 *
|
|
|
3752 * \param compute_pass a compute pass handle.
|
|
|
3753 * \param groupcount_x number of local workgroups to dispatch in the X
|
|
|
3754 * dimension.
|
|
|
3755 * \param groupcount_y number of local workgroups to dispatch in the Y
|
|
|
3756 * dimension.
|
|
|
3757 * \param groupcount_z number of local workgroups to dispatch in the Z
|
|
|
3758 * dimension.
|
|
|
3759 *
|
|
|
3760 * \since This function is available since SDL 3.2.0.
|
|
|
3761 */
|
|
|
3762 extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute(
|
|
|
3763 SDL_GPUComputePass *compute_pass,
|
|
|
3764 Uint32 groupcount_x,
|
|
|
3765 Uint32 groupcount_y,
|
|
|
3766 Uint32 groupcount_z);
|
|
|
3767
|
|
|
3768 /**
|
|
|
3769 * Dispatches compute work with parameters set from a buffer.
|
|
|
3770 *
|
|
|
3771 * The buffer layout should match the layout of
|
|
|
3772 * SDL_GPUIndirectDispatchCommand. You must not call this function before
|
|
|
3773 * binding a compute pipeline.
|
|
|
3774 *
|
|
|
3775 * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and
|
|
|
3776 * the dispatches write to the same resource region as each other, there is no
|
|
|
3777 * guarantee of which order the writes will occur. If the write order matters,
|
|
|
3778 * you MUST end the compute pass and begin another one.
|
|
|
3779 *
|
|
|
3780 * \param compute_pass a compute pass handle.
|
|
|
3781 * \param buffer a buffer containing dispatch parameters.
|
|
|
3782 * \param offset the offset to start reading from the dispatch buffer.
|
|
|
3783 *
|
|
|
3784 * \since This function is available since SDL 3.2.0.
|
|
|
3785 */
|
|
|
3786 extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect(
|
|
|
3787 SDL_GPUComputePass *compute_pass,
|
|
|
3788 SDL_GPUBuffer *buffer,
|
|
|
3789 Uint32 offset);
|
|
|
3790
|
|
|
3791 /**
|
|
|
3792 * Ends the current compute pass.
|
|
|
3793 *
|
|
|
3794 * All bound compute state on the command buffer is unset. The compute pass
|
|
|
3795 * handle is now invalid.
|
|
|
3796 *
|
|
|
3797 * \param compute_pass a compute pass handle.
|
|
|
3798 *
|
|
|
3799 * \since This function is available since SDL 3.2.0.
|
|
|
3800 */
|
|
|
3801 extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass(
|
|
|
3802 SDL_GPUComputePass *compute_pass);
|
|
|
3803
|
|
|
3804 /* TransferBuffer Data */
|
|
|
3805
|
|
|
3806 /**
|
|
|
3807 * Maps a transfer buffer into application address space.
|
|
|
3808 *
|
|
|
3809 * You must unmap the transfer buffer before encoding upload commands. The
|
|
|
3810 * memory is owned by the graphics driver - do NOT call SDL_free() on the
|
|
|
3811 * returned pointer.
|
|
|
3812 *
|
|
|
3813 * \param device a GPU context.
|
|
|
3814 * \param transfer_buffer a transfer buffer.
|
|
|
3815 * \param cycle if true, cycles the transfer buffer if it is already bound.
|
|
|
3816 * \returns the address of the mapped transfer buffer memory, or NULL on
|
|
|
3817 * failure; call SDL_GetError() for more information.
|
|
|
3818 *
|
|
|
3819 * \since This function is available since SDL 3.2.0.
|
|
|
3820 */
|
|
|
3821 extern SDL_DECLSPEC void * SDLCALL SDL_MapGPUTransferBuffer(
|
|
|
3822 SDL_GPUDevice *device,
|
|
|
3823 SDL_GPUTransferBuffer *transfer_buffer,
|
|
|
3824 bool cycle);
|
|
|
3825
|
|
|
3826 /**
|
|
|
3827 * Unmaps a previously mapped transfer buffer.
|
|
|
3828 *
|
|
|
3829 * \param device a GPU context.
|
|
|
3830 * \param transfer_buffer a previously mapped transfer buffer.
|
|
|
3831 *
|
|
|
3832 * \since This function is available since SDL 3.2.0.
|
|
|
3833 */
|
|
|
3834 extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer(
|
|
|
3835 SDL_GPUDevice *device,
|
|
|
3836 SDL_GPUTransferBuffer *transfer_buffer);
|
|
|
3837
|
|
|
3838 /* Copy Pass */
|
|
|
3839
|
|
|
3840 /**
|
|
|
3841 * Begins a copy pass on a command buffer.
|
|
|
3842 *
|
|
|
3843 * All operations related to copying to or from buffers or textures take place
|
|
|
3844 * inside a copy pass. You must not begin another copy pass, or a render pass
|
|
|
3845 * or compute pass before ending the copy pass.
|
|
|
3846 *
|
|
|
3847 * \param command_buffer a command buffer.
|
|
|
3848 * \returns a copy pass handle.
|
|
|
3849 *
|
|
|
3850 * \since This function is available since SDL 3.2.0.
|
|
|
3851 *
|
|
|
3852 * \sa SDL_EndGPUCopyPass
|
|
|
3853 */
|
|
|
3854 extern SDL_DECLSPEC SDL_GPUCopyPass * SDLCALL SDL_BeginGPUCopyPass(
|
|
|
3855 SDL_GPUCommandBuffer *command_buffer);
|
|
|
3856
|
|
|
3857 /**
|
|
|
3858 * Uploads data from a transfer buffer to a texture.
|
|
|
3859 *
|
|
|
3860 * The upload occurs on the GPU timeline. You may assume that the upload has
|
|
|
3861 * finished in subsequent commands.
|
|
|
3862 *
|
|
|
3863 * You must align the data in the transfer buffer to a multiple of the texel
|
|
|
3864 * size of the texture format.
|
|
|
3865 *
|
|
|
3866 * \param copy_pass a copy pass handle.
|
|
|
3867 * \param source the source transfer buffer with image layout information.
|
|
|
3868 * \param destination the destination texture region.
|
|
|
3869 * \param cycle if true, cycles the texture if the texture is bound, otherwise
|
|
|
3870 * overwrites the data.
|
|
|
3871 *
|
|
|
3872 * \since This function is available since SDL 3.2.0.
|
|
|
3873 */
|
|
|
3874 extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture(
|
|
|
3875 SDL_GPUCopyPass *copy_pass,
|
|
|
3876 const SDL_GPUTextureTransferInfo *source,
|
|
|
3877 const SDL_GPUTextureRegion *destination,
|
|
|
3878 bool cycle);
|
|
|
3879
|
|
|
3880 /**
|
|
|
3881 * Uploads data from a transfer buffer to a buffer.
|
|
|
3882 *
|
|
|
3883 * The upload occurs on the GPU timeline. You may assume that the upload has
|
|
|
3884 * finished in subsequent commands.
|
|
|
3885 *
|
|
|
3886 * \param copy_pass a copy pass handle.
|
|
|
3887 * \param source the source transfer buffer with offset.
|
|
|
3888 * \param destination the destination buffer with offset and size.
|
|
|
3889 * \param cycle if true, cycles the buffer if it is already bound, otherwise
|
|
|
3890 * overwrites the data.
|
|
|
3891 *
|
|
|
3892 * \since This function is available since SDL 3.2.0.
|
|
|
3893 */
|
|
|
3894 extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer(
|
|
|
3895 SDL_GPUCopyPass *copy_pass,
|
|
|
3896 const SDL_GPUTransferBufferLocation *source,
|
|
|
3897 const SDL_GPUBufferRegion *destination,
|
|
|
3898 bool cycle);
|
|
|
3899
|
|
|
3900 /**
|
|
|
3901 * Performs a texture-to-texture copy.
|
|
|
3902 *
|
|
|
3903 * This copy occurs on the GPU timeline. You may assume the copy has finished
|
|
|
3904 * in subsequent commands.
|
|
|
3905 *
|
|
|
3906 * This function does not support copying between depth and color textures.
|
|
|
3907 * For those, copy the texture to a buffer and then to the destination
|
|
|
3908 * texture.
|
|
|
3909 *
|
|
|
3910 * \param copy_pass a copy pass handle.
|
|
|
3911 * \param source a source texture region.
|
|
|
3912 * \param destination a destination texture region.
|
|
|
3913 * \param w the width of the region to copy.
|
|
|
3914 * \param h the height of the region to copy.
|
|
|
3915 * \param d the depth of the region to copy.
|
|
|
3916 * \param cycle if true, cycles the destination texture if the destination
|
|
|
3917 * texture is bound, otherwise overwrites the data.
|
|
|
3918 *
|
|
|
3919 * \since This function is available since SDL 3.2.0.
|
|
|
3920 */
|
|
|
3921 extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture(
|
|
|
3922 SDL_GPUCopyPass *copy_pass,
|
|
|
3923 const SDL_GPUTextureLocation *source,
|
|
|
3924 const SDL_GPUTextureLocation *destination,
|
|
|
3925 Uint32 w,
|
|
|
3926 Uint32 h,
|
|
|
3927 Uint32 d,
|
|
|
3928 bool cycle);
|
|
|
3929
|
|
|
3930 /**
|
|
|
3931 * Performs a buffer-to-buffer copy.
|
|
|
3932 *
|
|
|
3933 * This copy occurs on the GPU timeline. You may assume the copy has finished
|
|
|
3934 * in subsequent commands.
|
|
|
3935 *
|
|
|
3936 * \param copy_pass a copy pass handle.
|
|
|
3937 * \param source the buffer and offset to copy from.
|
|
|
3938 * \param destination the buffer and offset to copy to.
|
|
|
3939 * \param size the length of the buffer to copy.
|
|
|
3940 * \param cycle if true, cycles the destination buffer if it is already bound,
|
|
|
3941 * otherwise overwrites the data.
|
|
|
3942 *
|
|
|
3943 * \since This function is available since SDL 3.2.0.
|
|
|
3944 */
|
|
|
3945 extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer(
|
|
|
3946 SDL_GPUCopyPass *copy_pass,
|
|
|
3947 const SDL_GPUBufferLocation *source,
|
|
|
3948 const SDL_GPUBufferLocation *destination,
|
|
|
3949 Uint32 size,
|
|
|
3950 bool cycle);
|
|
|
3951
|
|
|
3952 /**
|
|
|
3953 * Copies data from a texture to a transfer buffer on the GPU timeline.
|
|
|
3954 *
|
|
|
3955 * This data is not guaranteed to be copied until the command buffer fence is
|
|
|
3956 * signaled.
|
|
|
3957 *
|
|
|
3958 * \param copy_pass a copy pass handle.
|
|
|
3959 * \param source the source texture region.
|
|
|
3960 * \param destination the destination transfer buffer with image layout
|
|
|
3961 * information.
|
|
|
3962 *
|
|
|
3963 * \since This function is available since SDL 3.2.0.
|
|
|
3964 */
|
|
|
3965 extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture(
|
|
|
3966 SDL_GPUCopyPass *copy_pass,
|
|
|
3967 const SDL_GPUTextureRegion *source,
|
|
|
3968 const SDL_GPUTextureTransferInfo *destination);
|
|
|
3969
|
|
|
3970 /**
|
|
|
3971 * Copies data from a buffer to a transfer buffer on the GPU timeline.
|
|
|
3972 *
|
|
|
3973 * This data is not guaranteed to be copied until the command buffer fence is
|
|
|
3974 * signaled.
|
|
|
3975 *
|
|
|
3976 * \param copy_pass a copy pass handle.
|
|
|
3977 * \param source the source buffer with offset and size.
|
|
|
3978 * \param destination the destination transfer buffer with offset.
|
|
|
3979 *
|
|
|
3980 * \since This function is available since SDL 3.2.0.
|
|
|
3981 */
|
|
|
3982 extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer(
|
|
|
3983 SDL_GPUCopyPass *copy_pass,
|
|
|
3984 const SDL_GPUBufferRegion *source,
|
|
|
3985 const SDL_GPUTransferBufferLocation *destination);
|
|
|
3986
|
|
|
3987 /**
|
|
|
3988 * Ends the current copy pass.
|
|
|
3989 *
|
|
|
3990 * \param copy_pass a copy pass handle.
|
|
|
3991 *
|
|
|
3992 * \since This function is available since SDL 3.2.0.
|
|
|
3993 */
|
|
|
3994 extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass(
|
|
|
3995 SDL_GPUCopyPass *copy_pass);
|
|
|
3996
|
|
|
3997 /**
|
|
|
3998 * Generates mipmaps for the given texture.
|
|
|
3999 *
|
|
|
4000 * This function must not be called inside of any pass.
|
|
|
4001 *
|
|
|
4002 * \param command_buffer a command_buffer.
|
|
|
4003 * \param texture a texture with more than 1 mip level.
|
|
|
4004 *
|
|
|
4005 * \since This function is available since SDL 3.2.0.
|
|
|
4006 */
|
|
|
4007 extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture(
|
|
|
4008 SDL_GPUCommandBuffer *command_buffer,
|
|
|
4009 SDL_GPUTexture *texture);
|
|
|
4010
|
|
|
4011 /**
|
|
|
4012 * Blits from a source texture region to a destination texture region.
|
|
|
4013 *
|
|
|
4014 * This function must not be called inside of any pass.
|
|
|
4015 *
|
|
|
4016 * \param command_buffer a command buffer.
|
|
|
4017 * \param info the blit info struct containing the blit parameters.
|
|
|
4018 *
|
|
|
4019 * \since This function is available since SDL 3.2.0.
|
|
|
4020 */
|
|
|
4021 extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture(
|
|
|
4022 SDL_GPUCommandBuffer *command_buffer,
|
|
|
4023 const SDL_GPUBlitInfo *info);
|
|
|
4024
|
|
|
4025 /* Submission/Presentation */
|
|
|
4026
|
|
|
4027 /**
|
|
|
4028 * Determines whether a swapchain composition is supported by the window.
|
|
|
4029 *
|
|
|
4030 * The window must be claimed before calling this function.
|
|
|
4031 *
|
|
|
4032 * \param device a GPU context.
|
|
|
4033 * \param window an SDL_Window.
|
|
|
4034 * \param swapchain_composition the swapchain composition to check.
|
|
|
4035 * \returns true if supported, false if unsupported.
|
|
|
4036 *
|
|
|
4037 * \since This function is available since SDL 3.2.0.
|
|
|
4038 *
|
|
|
4039 * \sa SDL_ClaimWindowForGPUDevice
|
|
|
4040 */
|
|
|
4041 extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition(
|
|
|
4042 SDL_GPUDevice *device,
|
|
|
4043 SDL_Window *window,
|
|
|
4044 SDL_GPUSwapchainComposition swapchain_composition);
|
|
|
4045
|
|
|
4046 /**
|
|
|
4047 * Determines whether a presentation mode is supported by the window.
|
|
|
4048 *
|
|
|
4049 * The window must be claimed before calling this function.
|
|
|
4050 *
|
|
|
4051 * \param device a GPU context.
|
|
|
4052 * \param window an SDL_Window.
|
|
|
4053 * \param present_mode the presentation mode to check.
|
|
|
4054 * \returns true if supported, false if unsupported.
|
|
|
4055 *
|
|
|
4056 * \since This function is available since SDL 3.2.0.
|
|
|
4057 *
|
|
|
4058 * \sa SDL_ClaimWindowForGPUDevice
|
|
|
4059 */
|
|
|
4060 extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode(
|
|
|
4061 SDL_GPUDevice *device,
|
|
|
4062 SDL_Window *window,
|
|
|
4063 SDL_GPUPresentMode present_mode);
|
|
|
4064
|
|
|
4065 /**
|
|
|
4066 * Claims a window, creating a swapchain structure for it.
|
|
|
4067 *
|
|
|
4068 * This must be called before SDL_AcquireGPUSwapchainTexture is called using
|
|
|
4069 * the window. You should only call this function from the thread that created
|
|
|
4070 * the window.
|
|
|
4071 *
|
|
|
4072 * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and
|
|
|
4073 * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain
|
|
|
4074 * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the
|
|
|
4075 * window.
|
|
|
4076 *
|
|
|
4077 * \param device a GPU context.
|
|
|
4078 * \param window an SDL_Window.
|
|
|
4079 * \returns true on success, or false on failure; call SDL_GetError() for more
|
|
|
4080 * information.
|
|
|
4081 *
|
|
|
4082 * \threadsafety This function should only be called from the thread that
|
|
|
4083 * created the window.
|
|
|
4084 *
|
|
|
4085 * \since This function is available since SDL 3.2.0.
|
|
|
4086 *
|
|
|
4087 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
4088 * \sa SDL_ReleaseWindowFromGPUDevice
|
|
|
4089 * \sa SDL_WindowSupportsGPUPresentMode
|
|
|
4090 * \sa SDL_WindowSupportsGPUSwapchainComposition
|
|
|
4091 */
|
|
|
4092 extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice(
|
|
|
4093 SDL_GPUDevice *device,
|
|
|
4094 SDL_Window *window);
|
|
|
4095
|
|
|
4096 /**
|
|
|
4097 * Unclaims a window, destroying its swapchain structure.
|
|
|
4098 *
|
|
|
4099 * \param device a GPU context.
|
|
|
4100 * \param window an SDL_Window that has been claimed.
|
|
|
4101 *
|
|
|
4102 * \since This function is available since SDL 3.2.0.
|
|
|
4103 *
|
|
|
4104 * \sa SDL_ClaimWindowForGPUDevice
|
|
|
4105 */
|
|
|
4106 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice(
|
|
|
4107 SDL_GPUDevice *device,
|
|
|
4108 SDL_Window *window);
|
|
|
4109
|
|
|
4110 /**
|
|
|
4111 * Changes the swapchain parameters for the given claimed window.
|
|
|
4112 *
|
|
|
4113 * This function will fail if the requested present mode or swapchain
|
|
|
4114 * composition are unsupported by the device. Check if the parameters are
|
|
|
4115 * supported via SDL_WindowSupportsGPUPresentMode /
|
|
|
4116 * SDL_WindowSupportsGPUSwapchainComposition prior to calling this function.
|
|
|
4117 *
|
|
|
4118 * SDL_GPU_PRESENTMODE_VSYNC with SDL_GPU_SWAPCHAINCOMPOSITION_SDR is always
|
|
|
4119 * supported.
|
|
|
4120 *
|
|
|
4121 * \param device a GPU context.
|
|
|
4122 * \param window an SDL_Window that has been claimed.
|
|
|
4123 * \param swapchain_composition the desired composition of the swapchain.
|
|
|
4124 * \param present_mode the desired present mode for the swapchain.
|
|
|
4125 * \returns true if successful, false on error; call SDL_GetError() for more
|
|
|
4126 * information.
|
|
|
4127 *
|
|
|
4128 * \since This function is available since SDL 3.2.0.
|
|
|
4129 *
|
|
|
4130 * \sa SDL_WindowSupportsGPUPresentMode
|
|
|
4131 * \sa SDL_WindowSupportsGPUSwapchainComposition
|
|
|
4132 */
|
|
|
4133 extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters(
|
|
|
4134 SDL_GPUDevice *device,
|
|
|
4135 SDL_Window *window,
|
|
|
4136 SDL_GPUSwapchainComposition swapchain_composition,
|
|
|
4137 SDL_GPUPresentMode present_mode);
|
|
|
4138
|
|
|
4139 /**
|
|
|
4140 * Configures the maximum allowed number of frames in flight.
|
|
|
4141 *
|
|
|
4142 * The default value when the device is created is 2. This means that after
|
|
|
4143 * you have submitted 2 frames for presentation, if the GPU has not finished
|
|
|
4144 * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the
|
|
|
4145 * swapchain texture pointer with NULL, and
|
|
|
4146 * SDL_WaitAndAcquireGPUSwapchainTexture() will block.
|
|
|
4147 *
|
|
|
4148 * Higher values increase throughput at the expense of visual latency. Lower
|
|
|
4149 * values decrease visual latency at the expense of throughput.
|
|
|
4150 *
|
|
|
4151 * Note that calling this function will stall and flush the command queue to
|
|
|
4152 * prevent synchronization issues.
|
|
|
4153 *
|
|
|
4154 * The minimum value of allowed frames in flight is 1, and the maximum is 3.
|
|
|
4155 *
|
|
|
4156 * \param device a GPU context.
|
|
|
4157 * \param allowed_frames_in_flight the maximum number of frames that can be
|
|
|
4158 * pending on the GPU.
|
|
|
4159 * \returns true if successful, false on error; call SDL_GetError() for more
|
|
|
4160 * information.
|
|
|
4161 *
|
|
|
4162 * \since This function is available since SDL 3.2.0.
|
|
|
4163 */
|
|
|
4164 extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight(
|
|
|
4165 SDL_GPUDevice *device,
|
|
|
4166 Uint32 allowed_frames_in_flight);
|
|
|
4167
|
|
|
4168 /**
|
|
|
4169 * Obtains the texture format of the swapchain for the given window.
|
|
|
4170 *
|
|
|
4171 * Note that this format can change if the swapchain parameters change.
|
|
|
4172 *
|
|
|
4173 * \param device a GPU context.
|
|
|
4174 * \param window an SDL_Window that has been claimed.
|
|
|
4175 * \returns the texture format of the swapchain.
|
|
|
4176 *
|
|
|
4177 * \since This function is available since SDL 3.2.0.
|
|
|
4178 */
|
|
|
4179 extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat(
|
|
|
4180 SDL_GPUDevice *device,
|
|
|
4181 SDL_Window *window);
|
|
|
4182
|
|
|
4183 /**
|
|
|
4184 * Acquire a texture to use in presentation.
|
|
|
4185 *
|
|
|
4186 * When a swapchain texture is acquired on a command buffer, it will
|
|
|
4187 * automatically be submitted for presentation when the command buffer is
|
|
|
4188 * submitted. The swapchain texture should only be referenced by the command
|
|
|
4189 * buffer used to acquire it.
|
|
|
4190 *
|
|
|
4191 * This function will fill the swapchain texture handle with NULL if too many
|
|
|
4192 * frames are in flight. This is not an error. This NULL pointer should not be
|
|
|
4193 * passed back into SDL. Instead, it should be considered as an indication to
|
|
|
4194 * wait until the swapchain is available.
|
|
|
4195 *
|
|
|
4196 * If you use this function, it is possible to create a situation where many
|
|
|
4197 * command buffers are allocated while the rendering context waits for the GPU
|
|
|
4198 * to catch up, which will cause memory usage to grow. You should use
|
|
|
4199 * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing
|
|
|
4200 * with timing.
|
|
|
4201 *
|
|
|
4202 * The swapchain texture is managed by the implementation and must not be
|
|
|
4203 * freed by the user. You MUST NOT call this function from any thread other
|
|
|
4204 * than the one that created the window.
|
|
|
4205 *
|
|
|
4206 * \param command_buffer a command buffer.
|
|
|
4207 * \param window a window that has been claimed.
|
|
|
4208 * \param swapchain_texture a pointer filled in with a swapchain texture
|
|
|
4209 * handle.
|
|
|
4210 * \param swapchain_texture_width a pointer filled in with the swapchain
|
|
|
4211 * texture width, may be NULL.
|
|
|
4212 * \param swapchain_texture_height a pointer filled in with the swapchain
|
|
|
4213 * texture height, may be NULL.
|
|
|
4214 * \returns true on success, false on error; call SDL_GetError() for more
|
|
|
4215 * information.
|
|
|
4216 *
|
|
|
4217 * \threadsafety This function should only be called from the thread that
|
|
|
4218 * created the window.
|
|
|
4219 *
|
|
|
4220 * \since This function is available since SDL 3.2.0.
|
|
|
4221 *
|
|
|
4222 * \sa SDL_ClaimWindowForGPUDevice
|
|
|
4223 * \sa SDL_SubmitGPUCommandBuffer
|
|
|
4224 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
4225 * \sa SDL_CancelGPUCommandBuffer
|
|
|
4226 * \sa SDL_GetWindowSizeInPixels
|
|
|
4227 * \sa SDL_WaitForGPUSwapchain
|
|
|
4228 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
4229 * \sa SDL_SetGPUAllowedFramesInFlight
|
|
|
4230 */
|
|
|
4231 extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture(
|
|
|
4232 SDL_GPUCommandBuffer *command_buffer,
|
|
|
4233 SDL_Window *window,
|
|
|
4234 SDL_GPUTexture **swapchain_texture,
|
|
|
4235 Uint32 *swapchain_texture_width,
|
|
|
4236 Uint32 *swapchain_texture_height);
|
|
|
4237
|
|
|
4238 /**
|
|
|
4239 * Blocks the thread until a swapchain texture is available to be acquired.
|
|
|
4240 *
|
|
|
4241 * \param device a GPU context.
|
|
|
4242 * \param window a window that has been claimed.
|
|
|
4243 * \returns true on success, false on failure; call SDL_GetError() for more
|
|
|
4244 * information.
|
|
|
4245 *
|
|
|
4246 * \threadsafety This function should only be called from the thread that
|
|
|
4247 * created the window.
|
|
|
4248 *
|
|
|
4249 * \since This function is available since SDL 3.2.0.
|
|
|
4250 *
|
|
|
4251 * \sa SDL_AcquireGPUSwapchainTexture
|
|
|
4252 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
4253 * \sa SDL_SetGPUAllowedFramesInFlight
|
|
|
4254 */
|
|
|
4255 extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain(
|
|
|
4256 SDL_GPUDevice *device,
|
|
|
4257 SDL_Window *window);
|
|
|
4258
|
|
|
4259 /**
|
|
|
4260 * Blocks the thread until a swapchain texture is available to be acquired,
|
|
|
4261 * and then acquires it.
|
|
|
4262 *
|
|
|
4263 * When a swapchain texture is acquired on a command buffer, it will
|
|
|
4264 * automatically be submitted for presentation when the command buffer is
|
|
|
4265 * submitted. The swapchain texture should only be referenced by the command
|
|
|
4266 * buffer used to acquire it. It is an error to call
|
|
|
4267 * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired.
|
|
|
4268 *
|
|
|
4269 * This function can fill the swapchain texture handle with NULL in certain
|
|
|
4270 * cases, for example if the window is minimized. This is not an error. You
|
|
|
4271 * should always make sure to check whether the pointer is NULL before
|
|
|
4272 * actually using it.
|
|
|
4273 *
|
|
|
4274 * The swapchain texture is managed by the implementation and must not be
|
|
|
4275 * freed by the user. You MUST NOT call this function from any thread other
|
|
|
4276 * than the one that created the window.
|
|
|
4277 *
|
|
|
4278 * The swapchain texture is write-only and cannot be used as a sampler or for
|
|
|
4279 * another reading operation.
|
|
|
4280 *
|
|
|
4281 * \param command_buffer a command buffer.
|
|
|
4282 * \param window a window that has been claimed.
|
|
|
4283 * \param swapchain_texture a pointer filled in with a swapchain texture
|
|
|
4284 * handle.
|
|
|
4285 * \param swapchain_texture_width a pointer filled in with the swapchain
|
|
|
4286 * texture width, may be NULL.
|
|
|
4287 * \param swapchain_texture_height a pointer filled in with the swapchain
|
|
|
4288 * texture height, may be NULL.
|
|
|
4289 * \returns true on success, false on error; call SDL_GetError() for more
|
|
|
4290 * information.
|
|
|
4291 *
|
|
|
4292 * \threadsafety This function should only be called from the thread that
|
|
|
4293 * created the window.
|
|
|
4294 *
|
|
|
4295 * \since This function is available since SDL 3.2.0.
|
|
|
4296 *
|
|
|
4297 * \sa SDL_SubmitGPUCommandBuffer
|
|
|
4298 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
4299 * \sa SDL_AcquireGPUSwapchainTexture
|
|
|
4300 */
|
|
|
4301 extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture(
|
|
|
4302 SDL_GPUCommandBuffer *command_buffer,
|
|
|
4303 SDL_Window *window,
|
|
|
4304 SDL_GPUTexture **swapchain_texture,
|
|
|
4305 Uint32 *swapchain_texture_width,
|
|
|
4306 Uint32 *swapchain_texture_height);
|
|
|
4307
|
|
|
4308 /**
|
|
|
4309 * Submits a command buffer so its commands can be processed on the GPU.
|
|
|
4310 *
|
|
|
4311 * It is invalid to use the command buffer after this is called.
|
|
|
4312 *
|
|
|
4313 * This must be called from the thread the command buffer was acquired on.
|
|
|
4314 *
|
|
|
4315 * All commands in the submission are guaranteed to begin executing before any
|
|
|
4316 * command in a subsequent submission begins executing.
|
|
|
4317 *
|
|
|
4318 * \param command_buffer a command buffer.
|
|
|
4319 * \returns true on success, false on failure; call SDL_GetError() for more
|
|
|
4320 * information.
|
|
|
4321 *
|
|
|
4322 * \since This function is available since SDL 3.2.0.
|
|
|
4323 *
|
|
|
4324 * \sa SDL_AcquireGPUCommandBuffer
|
|
|
4325 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
4326 * \sa SDL_AcquireGPUSwapchainTexture
|
|
|
4327 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
4328 */
|
|
|
4329 extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer(
|
|
|
4330 SDL_GPUCommandBuffer *command_buffer);
|
|
|
4331
|
|
|
4332 /**
|
|
|
4333 * Submits a command buffer so its commands can be processed on the GPU, and
|
|
|
4334 * acquires a fence associated with the command buffer.
|
|
|
4335 *
|
|
|
4336 * You must release this fence when it is no longer needed or it will cause a
|
|
|
4337 * leak. It is invalid to use the command buffer after this is called.
|
|
|
4338 *
|
|
|
4339 * This must be called from the thread the command buffer was acquired on.
|
|
|
4340 *
|
|
|
4341 * All commands in the submission are guaranteed to begin executing before any
|
|
|
4342 * command in a subsequent submission begins executing.
|
|
|
4343 *
|
|
|
4344 * \param command_buffer a command buffer.
|
|
|
4345 * \returns a fence associated with the command buffer, or NULL on failure;
|
|
|
4346 * call SDL_GetError() for more information.
|
|
|
4347 *
|
|
|
4348 * \since This function is available since SDL 3.2.0.
|
|
|
4349 *
|
|
|
4350 * \sa SDL_AcquireGPUCommandBuffer
|
|
|
4351 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
4352 * \sa SDL_AcquireGPUSwapchainTexture
|
|
|
4353 * \sa SDL_SubmitGPUCommandBuffer
|
|
|
4354 * \sa SDL_ReleaseGPUFence
|
|
|
4355 */
|
|
|
4356 extern SDL_DECLSPEC SDL_GPUFence * SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence(
|
|
|
4357 SDL_GPUCommandBuffer *command_buffer);
|
|
|
4358
|
|
|
4359 /**
|
|
|
4360 * Cancels a command buffer.
|
|
|
4361 *
|
|
|
4362 * None of the enqueued commands are executed.
|
|
|
4363 *
|
|
|
4364 * It is an error to call this function after a swapchain texture has been
|
|
|
4365 * acquired.
|
|
|
4366 *
|
|
|
4367 * This must be called from the thread the command buffer was acquired on.
|
|
|
4368 *
|
|
|
4369 * You must not reference the command buffer after calling this function.
|
|
|
4370 *
|
|
|
4371 * \param command_buffer a command buffer.
|
|
|
4372 * \returns true on success, false on error; call SDL_GetError() for more
|
|
|
4373 * information.
|
|
|
4374 *
|
|
|
4375 * \since This function is available since SDL 3.2.0.
|
|
|
4376 *
|
|
|
4377 * \sa SDL_WaitAndAcquireGPUSwapchainTexture
|
|
|
4378 * \sa SDL_AcquireGPUCommandBuffer
|
|
|
4379 * \sa SDL_AcquireGPUSwapchainTexture
|
|
|
4380 */
|
|
|
4381 extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer(
|
|
|
4382 SDL_GPUCommandBuffer *command_buffer);
|
|
|
4383
|
|
|
4384 /**
|
|
|
4385 * Blocks the thread until the GPU is completely idle.
|
|
|
4386 *
|
|
|
4387 * \param device a GPU context.
|
|
|
4388 * \returns true on success, false on failure; call SDL_GetError() for more
|
|
|
4389 * information.
|
|
|
4390 *
|
|
|
4391 * \since This function is available since SDL 3.2.0.
|
|
|
4392 *
|
|
|
4393 * \sa SDL_WaitForGPUFences
|
|
|
4394 */
|
|
|
4395 extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle(
|
|
|
4396 SDL_GPUDevice *device);
|
|
|
4397
|
|
|
4398 /**
|
|
|
4399 * Blocks the thread until the given fences are signaled.
|
|
|
4400 *
|
|
|
4401 * \param device a GPU context.
|
|
|
4402 * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all
|
|
|
4403 * fences to be signaled.
|
|
|
4404 * \param fences an array of fences to wait on.
|
|
|
4405 * \param num_fences the number of fences in the fences array.
|
|
|
4406 * \returns true on success, false on failure; call SDL_GetError() for more
|
|
|
4407 * information.
|
|
|
4408 *
|
|
|
4409 * \since This function is available since SDL 3.2.0.
|
|
|
4410 *
|
|
|
4411 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
4412 * \sa SDL_WaitForGPUIdle
|
|
|
4413 */
|
|
|
4414 extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences(
|
|
|
4415 SDL_GPUDevice *device,
|
|
|
4416 bool wait_all,
|
|
|
4417 SDL_GPUFence *const *fences,
|
|
|
4418 Uint32 num_fences);
|
|
|
4419
|
|
|
4420 /**
|
|
|
4421 * Checks the status of a fence.
|
|
|
4422 *
|
|
|
4423 * \param device a GPU context.
|
|
|
4424 * \param fence a fence.
|
|
|
4425 * \returns true if the fence is signaled, false if it is not.
|
|
|
4426 *
|
|
|
4427 * \since This function is available since SDL 3.2.0.
|
|
|
4428 *
|
|
|
4429 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
4430 */
|
|
|
4431 extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence(
|
|
|
4432 SDL_GPUDevice *device,
|
|
|
4433 SDL_GPUFence *fence);
|
|
|
4434
|
|
|
4435 /**
|
|
|
4436 * Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence.
|
|
|
4437 *
|
|
|
4438 * You must not reference the fence after calling this function.
|
|
|
4439 *
|
|
|
4440 * \param device a GPU context.
|
|
|
4441 * \param fence a fence.
|
|
|
4442 *
|
|
|
4443 * \since This function is available since SDL 3.2.0.
|
|
|
4444 *
|
|
|
4445 * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
|
|
|
4446 */
|
|
|
4447 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence(
|
|
|
4448 SDL_GPUDevice *device,
|
|
|
4449 SDL_GPUFence *fence);
|
|
|
4450
|
|
|
4451 /* Format Info */
|
|
|
4452
|
|
|
4453 /**
|
|
|
4454 * Obtains the texel block size for a texture format.
|
|
|
4455 *
|
|
|
4456 * \param format the texture format you want to know the texel size of.
|
|
|
4457 * \returns the texel block size of the texture format.
|
|
|
4458 *
|
|
|
4459 * \since This function is available since SDL 3.2.0.
|
|
|
4460 *
|
|
|
4461 * \sa SDL_UploadToGPUTexture
|
|
|
4462 */
|
|
|
4463 extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize(
|
|
|
4464 SDL_GPUTextureFormat format);
|
|
|
4465
|
|
|
4466 /**
|
|
|
4467 * Determines whether a texture format is supported for a given type and
|
|
|
4468 * usage.
|
|
|
4469 *
|
|
|
4470 * \param device a GPU context.
|
|
|
4471 * \param format the texture format to check.
|
|
|
4472 * \param type the type of texture (2D, 3D, Cube).
|
|
|
4473 * \param usage a bitmask of all usage scenarios to check.
|
|
|
4474 * \returns whether the texture format is supported for this type and usage.
|
|
|
4475 *
|
|
|
4476 * \since This function is available since SDL 3.2.0.
|
|
|
4477 */
|
|
|
4478 extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat(
|
|
|
4479 SDL_GPUDevice *device,
|
|
|
4480 SDL_GPUTextureFormat format,
|
|
|
4481 SDL_GPUTextureType type,
|
|
|
4482 SDL_GPUTextureUsageFlags usage);
|
|
|
4483
|
|
|
4484 /**
|
|
|
4485 * Determines if a sample count for a texture format is supported.
|
|
|
4486 *
|
|
|
4487 * \param device a GPU context.
|
|
|
4488 * \param format the texture format to check.
|
|
|
4489 * \param sample_count the sample count to check.
|
|
|
4490 * \returns whether the sample count is supported for this texture format.
|
|
|
4491 *
|
|
|
4492 * \since This function is available since SDL 3.2.0.
|
|
|
4493 */
|
|
|
4494 extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount(
|
|
|
4495 SDL_GPUDevice *device,
|
|
|
4496 SDL_GPUTextureFormat format,
|
|
|
4497 SDL_GPUSampleCount sample_count);
|
|
|
4498
|
|
|
4499 /**
|
|
|
4500 * Calculate the size in bytes of a texture format with dimensions.
|
|
|
4501 *
|
|
|
4502 * \param format a texture format.
|
|
|
4503 * \param width width in pixels.
|
|
|
4504 * \param height height in pixels.
|
|
|
4505 * \param depth_or_layer_count depth for 3D textures or layer count otherwise.
|
|
|
4506 * \returns the size of a texture with this format and dimensions.
|
|
|
4507 *
|
|
|
4508 * \since This function is available since SDL 3.2.0.
|
|
|
4509 */
|
|
|
4510 extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize(
|
|
|
4511 SDL_GPUTextureFormat format,
|
|
|
4512 Uint32 width,
|
|
|
4513 Uint32 height,
|
|
|
4514 Uint32 depth_or_layer_count);
|
|
|
4515
|
|
|
4516 /**
|
|
|
4517 * Get the SDL pixel format corresponding to a GPU texture format.
|
|
|
4518 *
|
|
|
4519 * \param format a texture format.
|
|
|
4520 * \returns the corresponding pixel format, or SDL_PIXELFORMAT_UNKNOWN if
|
|
|
4521 * there is no corresponding pixel format.
|
|
|
4522 *
|
|
|
4523 * \since This function is available since SDL 3.4.0.
|
|
|
4524 */
|
|
|
4525 extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatFromGPUTextureFormat(SDL_GPUTextureFormat format);
|
|
|
4526
|
|
|
4527 /**
|
|
|
4528 * Get the GPU texture format corresponding to an SDL pixel format.
|
|
|
4529 *
|
|
|
4530 * \param format a pixel format.
|
|
|
4531 * \returns the corresponding GPU texture format, or
|
|
|
4532 * SDL_GPU_TEXTUREFORMAT_INVALID if there is no corresponding GPU
|
|
|
4533 * texture format.
|
|
|
4534 *
|
|
|
4535 * \since This function is available since SDL 3.4.0.
|
|
|
4536 */
|
|
|
4537 extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUTextureFormatFromPixelFormat(SDL_PixelFormat format);
|
|
|
4538
|
|
|
4539 #ifdef SDL_PLATFORM_GDK
|
|
|
4540
|
|
|
4541 /**
|
|
|
4542 * Call this to suspend GPU operation on Xbox when you receive the
|
|
|
4543 * SDL_EVENT_DID_ENTER_BACKGROUND event.
|
|
|
4544 *
|
|
|
4545 * Do NOT call any SDL_GPU functions after calling this function! This must
|
|
|
4546 * also be called before calling SDL_GDKSuspendComplete.
|
|
|
4547 *
|
|
|
4548 * \param device a GPU context.
|
|
|
4549 *
|
|
|
4550 * \since This function is available since SDL 3.2.0.
|
|
|
4551 *
|
|
|
4552 * \sa SDL_AddEventWatch
|
|
|
4553 */
|
|
|
4554 extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device);
|
|
|
4555
|
|
|
4556 /**
|
|
|
4557 * Call this to resume GPU operation on Xbox when you receive the
|
|
|
4558 * SDL_EVENT_WILL_ENTER_FOREGROUND event.
|
|
|
4559 *
|
|
|
4560 * When resuming, this function MUST be called before calling any other
|
|
|
4561 * SDL_GPU functions.
|
|
|
4562 *
|
|
|
4563 * \param device a GPU context.
|
|
|
4564 *
|
|
|
4565 * \since This function is available since SDL 3.2.0.
|
|
|
4566 *
|
|
|
4567 * \sa SDL_AddEventWatch
|
|
|
4568 */
|
|
|
4569 extern SDL_DECLSPEC void SDLCALL SDL_GDKResumeGPU(SDL_GPUDevice *device);
|
|
|
4570
|
|
|
4571 #endif /* SDL_PLATFORM_GDK */
|
|
|
4572
|
|
|
4573 #ifdef __cplusplus
|
|
|
4574 }
|
|
|
4575 #endif /* __cplusplus */
|
|
|
4576 #include <SDL3/SDL_close_code.h>
|
|
|
4577
|
|
|
4578 #endif /* SDL_gpu_h_ */
|
