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