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