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