devela::_dep::sdl3::sys

Module gpu

Available on crate feature dep_sdl3 only.
Expand description

The GPU API offers a cross-platform way for apps to talk to modern graphics hardware. It offers both 3D graphics and compute support, in the style of Metal, Vulkan, and Direct3D 12.

A basic workflow might be something like this:

The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to a window with SDL_ClaimWindowForGPUDevice()–although strictly speaking you can render offscreen entirely, perhaps for image processing, and not use a window at all.

Next the app prepares static data (things that are created once and used over and over). For example:

To render, the app creates one or more command buffers, with SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering instructions that will be submitted to the GPU in batch. Complex scenes can use multiple command buffers, maybe configured across multiple threads in parallel, as long as they are submitted in the correct order, but many apps will just need one command buffer per frame.

Rendering can happen to a texture (what other APIs call a “render target”) or it can happen to the swapchain texture (which is just a special texture that represents a window’s contents). The app can use SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window.

Rendering actually happens in a Render Pass, which is encoded into a command buffer. One can encode multiple render passes (or alternate between render and compute passes) in a single command buffer, but many apps might simply need a single render pass in a single command buffer. Render Passes can render to up to four color textures and one depth texture simultaneously. If the set of textures being rendered to needs to change, the Render Pass must be ended and a new one must be begun.

The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for each draw:

Then, make the actual draw commands with these states:

After all the drawing commands for a pass are complete, the app should call SDL_EndGPURenderPass(). Once a render pass ends all render-related state is reset.

The app can begin new Render Passes and make new draws in the same command buffer until the entire scene is rendered.

Once all of the render commands for the scene are complete, the app calls SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing.

If the app needs to read back data from texture or buffers, the API has an efficient way of doing this, provided that the app is willing to tolerate some latency. When the app uses SDL_DownloadFromGPUTexture() or SDL_DownloadFromGPUBuffer(), submitting the command buffer with SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that the app can poll or wait on in a thread. Once the fence indicates that the command buffer is done processing, it is safe to read the downloaded data. Make sure to call SDL_ReleaseGPUFence() when done with the fence.

The API also has “compute” support. The app calls SDL_BeginGPUComputePass() with compute-writeable textures and/or buffers, which can be written to in a compute shader. Then it sets states it needs for the compute dispatches:

Then, dispatch compute work:

For advanced users, this opens up powerful GPU-driven workflows.

Graphics and compute pipelines require the use of shaders, which as mentioned above are small programs executed on the GPU. Each backend (Vulkan, Metal, D3D12) requires a different shader format. When the app creates the GPU device, the app lets the device know which shader formats the app can provide. It will then select the appropriate backend depending on the available shader formats and the backends available on the platform. When creating shaders, the app must provide the correct shader format for the selected backend. If you would like to learn more about why the API works this way, there is a detailed blog post explaining this situation.

It is optimal for apps to pre-compile the shader formats they might use, but for ease of use SDL provides a separate project, SDL_shadercross , for performing runtime shader cross-compilation. It also has a CLI interface for offline precompilation as well.

This is an extremely quick overview that leaves out several important details. Already, though, one can see that GPU programming can be quite complex! If you just need simple 2D graphics, the Render API is much easier to use but still hardware-accelerated. That said, even for 2D applications the performance benefits and expressiveness of the GPU API are significant.

The GPU API targets a feature set with a wide range of hardware support and ease of portability. It is designed so that the app won’t have to branch itself by querying feature support. If you need cutting-edge features with limited hardware support, this API is probably not for you.

Examples demonstrating proper usage of this API can be found here .

§Performance considerations

Here are some basic tips for maximizing your rendering performance.

  • Beginning a new render pass is relatively expensive. Use as few render passes as you can.
  • Minimize the amount of state changes. For example, binding a pipeline is relatively cheap, but doing it hundreds of times when you don’t need to will slow the performance significantly.
  • Perform your data uploads as early as possible in the frame.
  • Don’t churn resources. Creating and releasing resources is expensive. It’s better to create what you need up front and cache it.
  • Don’t use uniform buffers for large amounts of data (more than a matrix or so). Use a storage buffer instead.
  • Use cycling correctly. There is a detailed explanation of cycling further below.
  • Use culling techniques to minimize pixel writes. The less writing the GPU has to do the better. Culling can be a very advanced topic but even simple culling techniques can boost performance significantly.

In general try to remember the golden rule of performance: doing things is more expensive than not doing things. Don’t Touch The Driver!

§FAQ

Question: When are you adding more advanced features, like ray tracing or mesh shaders?

Answer: We don’t have immediate plans to add more bleeding-edge features, but we certainly might in the future, when these features prove worthwhile, and reasonable to implement across several platforms and underlying APIs. So while these things are not in the “never” category, they are definitely not “near future” items either.

Question: Why is my shader not working?

Answer: A common oversight when using shaders is not properly laying out the shader resources/registers correctly. The GPU API is very strict with how it wants resources to be laid out and it’s difficult for the API to automatically validate shaders to see if they have a compatible layout. See the documentation for SDL_CreateGPUShader() and SDL_CreateGPUComputePipeline() for information on the expected layout.

Another common issue is not setting the correct number of samplers, textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader reflection to extract the required information from the shader automatically instead of manually filling in the struct’s values.

Question: My application isn’t performing very well. Is this the GPU API’s fault?

Answer: No. Long answer: The GPU API is a relatively thin layer over the underlying graphics API. While it’s possible that we have done something inefficiently, it’s very unlikely especially if you are relatively inexperienced with GPU rendering. Please see the performance tips above and make sure you are following them. Additionally, tools like RenderDoc can be very helpful for diagnosing incorrect behavior and performance issues.

§System Requirements

Vulkan: Supported on Windows, Linux, Nintendo Switch, and certain Android devices. Requires Vulkan 1.0 with the following extensions and device features:

  • VK_KHR_swapchain
  • VK_KHR_maintenance1
  • independentBlend
  • imageCubeArray
  • depthClamp
  • shaderClipDistance
  • drawIndirectFirstInstance

D3D12: Supported on Windows 10 or newer, Xbox One (GDK), and Xbox Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level 11_1.

Metal: Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware requirements vary by operating system:

  • macOS requires an Apple Silicon or Intel Mac2 family GPU
  • iOS/tvOS requires an A9 GPU or newer
  • iOS Simulator and tvOS Simulator are unsupported

§Uniform Data

Uniforms are for passing data to shaders. The uniform data will be constant across all executions of the shader.

There are 4 available uniform slots per shader stage (where the stages are vertex, fragment, and compute). Uniform data pushed to a slot on a stage keeps its value throughout the command buffer until you call the relevant Push function on that slot again.

For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, push the camera matrix at the start of the command buffer, and that data will be used for every subsequent draw call.

It is valid to push uniform data during a render or compute pass.

Uniforms are best for pushing small amounts of data. If you are pushing more than a matrix or two per call you should consider using a storage buffer instead.

§A Note On Cycling

When using a command buffer, operations do not occur immediately - they occur some time after the command buffer is submitted.

When a resource is used in a pending or active command buffer, it is considered to be “bound”. When a resource is no longer used in any pending or active command buffers, it is considered to be “unbound”.

If data resources are bound, it is unspecified when that data will be unbound unless you acquire a fence when submitting the command buffer and wait on it. However, this doesn’t mean you need to track resource usage manually.

All of the functions and structs that involve writing to a resource have a “cycle” bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all effectively function as ring buffers on internal resources. When cycle is true, if the resource is bound, the cycle rotates to the next unbound internal resource, or if none are available, a new one is created. This means you don’t have to worry about complex state tracking and synchronization as long as cycling is correctly employed.

For example: you can call SDL_MapGPUTransferBuffer(), write texture data, SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next time you write texture data to the transfer buffer, if you set the cycle param to true, you don’t have to worry about overwriting any data that is not yet uploaded.

Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. If you set cycle to true in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency.

Cycling will never undefine already bound data. When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. You must take care not to read undefined data.

Note that when cycling a texture, the entire texture will be cycled, even if only part of the texture is used in the call, so you must consider the entire texture to contain undefined data after cycling.

You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. It is OK to overwrite unreferenced data in a bound resource without cycling, but overwriting a section of data that has already been referenced will produce unexpected results.

Structs§

SDL_GPUBlendFactor
Specifies a blending factor to be used when pixels in a render target are blended with existing pixels in the texture.
SDL_GPUBlendOp
Specifies the operator to be used when pixels in a render target are blended with existing pixels in the texture.
SDL_GPUBlitInfo
A structure containing parameters for a blit command.
SDL_GPUBlitRegion
A structure specifying a region of a texture used in the blit operation.
SDL_GPUBuffer
An opaque handle representing a buffer.
SDL_GPUBufferBinding
A structure specifying parameters in a buffer binding call.
SDL_GPUBufferCreateInfo
A structure specifying the parameters of a buffer.
SDL_GPUBufferLocation
A structure specifying a location in a buffer.
SDL_GPUBufferRegion
A structure specifying a region of a buffer.
SDL_GPUColorTargetBlendState
A structure specifying the blend state of a color target.
SDL_GPUColorTargetDescription
A structure specifying the parameters of color targets used in a graphics pipeline.
SDL_GPUColorTargetInfo
A structure specifying the parameters of a color target used by a render pass.
SDL_GPUCommandBuffer
An opaque handle representing a command buffer.
SDL_GPUCompareOp
Specifies a comparison operator for depth, stencil and sampler operations.
SDL_GPUComputePass
An opaque handle representing a compute pass.
SDL_GPUComputePipeline
An opaque handle representing a compute pipeline.
SDL_GPUComputePipelineCreateInfo
A structure specifying the parameters of a compute pipeline state.
SDL_GPUCopyPass
An opaque handle representing a copy pass.
SDL_GPUCubeMapFace
Specifies the face of a cube map.
SDL_GPUCullMode
Specifies the facing direction in which triangle faces will be culled.
SDL_GPUDepthStencilState
A structure specifying the parameters of the graphics pipeline depth stencil state.
SDL_GPUDepthStencilTargetInfo
A structure specifying the parameters of a depth-stencil target used by a render pass.
SDL_GPUDevice
An opaque handle representing the SDL_GPU context.
SDL_GPUFence
An opaque handle representing a fence.
SDL_GPUFillMode
Specifies the fill mode of the graphics pipeline.
SDL_GPUFilter
Specifies a filter operation used by a sampler.
SDL_GPUFrontFace
Specifies the vertex winding that will cause a triangle to be determined to be front-facing.
SDL_GPUGraphicsPipeline
An opaque handle representing a graphics pipeline.
SDL_GPUGraphicsPipelineCreateInfo
A structure specifying the parameters of a graphics pipeline state.
SDL_GPUGraphicsPipelineTargetInfo
A structure specifying the descriptions of render targets used in a graphics pipeline.
SDL_GPUIndexElementSize
Specifies the size of elements in an index buffer.
SDL_GPUIndexedIndirectDrawCommand
A structure specifying the parameters of an indexed indirect draw command.
SDL_GPUIndirectDispatchCommand
A structure specifying the parameters of an indexed dispatch command.
SDL_GPUIndirectDrawCommand
A structure specifying the parameters of an indirect draw command.
SDL_GPULoadOp
Specifies how the contents of a texture attached to a render pass are treated at the beginning of the render pass.
SDL_GPUMultisampleState
A structure specifying the parameters of the graphics pipeline multisample state.
SDL_GPUPresentMode
Specifies the timing that will be used to present swapchain textures to the OS.
SDL_GPUPrimitiveType
Specifies the primitive topology of a graphics pipeline.
SDL_GPURasterizerState
A structure specifying the parameters of the graphics pipeline rasterizer state.
SDL_GPURenderPass
An opaque handle representing a render pass.
SDL_GPUSampleCount
Specifies the sample count of a texture.
SDL_GPUSampler
An opaque handle representing a sampler.
SDL_GPUSamplerAddressMode
Specifies behavior of texture sampling when the coordinates exceed the 0-1 range.
SDL_GPUSamplerCreateInfo
A structure specifying the parameters of a sampler.
SDL_GPUSamplerMipmapMode
Specifies a mipmap mode used by a sampler.
SDL_GPUShader
An opaque handle representing a compiled shader object.
SDL_GPUShaderCreateInfo
A structure specifying code and metadata for creating a shader object.
SDL_GPUShaderStage
Specifies which stage a shader program corresponds to.
SDL_GPUStencilOp
Specifies what happens to a stored stencil value if stencil tests fail or pass.
SDL_GPUStencilOpState
A structure specifying the stencil operation state of a graphics pipeline.
SDL_GPUStorageBufferReadWriteBinding
A structure specifying parameters related to binding buffers in a compute pass.
SDL_GPUStorageTextureReadWriteBinding
A structure specifying parameters related to binding textures in a compute pass.
SDL_GPUStoreOp
Specifies how the contents of a texture attached to a render pass are treated at the end of the render pass.
SDL_GPUSwapchainComposition
Specifies the texture format and colorspace of the swapchain textures.
SDL_GPUTexture
An opaque handle representing a texture.
SDL_GPUTextureCreateInfo
A structure specifying the parameters of a texture.
SDL_GPUTextureFormat
Specifies the pixel format of a texture.
SDL_GPUTextureLocation
A structure specifying a location in a texture.
SDL_GPUTextureRegion
A structure specifying a region of a texture.
SDL_GPUTextureSamplerBinding
A structure specifying parameters in a sampler binding call.
SDL_GPUTextureTransferInfo
A structure specifying parameters related to transferring data to or from a texture.
SDL_GPUTextureType
Specifies the type of a texture.
SDL_GPUTransferBuffer
An opaque handle representing a transfer buffer.
SDL_GPUTransferBufferCreateInfo
A structure specifying the parameters of a transfer buffer.
SDL_GPUTransferBufferLocation
A structure specifying a location in a transfer buffer.
SDL_GPUTransferBufferUsage
Specifies how a transfer buffer is intended to be used by the client.
SDL_GPUVertexAttribute
A structure specifying a vertex attribute.
SDL_GPUVertexBufferDescription
A structure specifying the parameters of vertex buffers used in a graphics pipeline.
SDL_GPUVertexElementFormat
Specifies the format of a vertex attribute.
SDL_GPUVertexInputRate
Specifies the rate at which vertex attributes are pulled from buffers.
SDL_GPUVertexInputState
A structure specifying the parameters of a graphics pipeline vertex input state.
SDL_GPUViewport
A structure specifying a viewport.

Constants§

SDL_GPU_BLENDFACTOR_CONSTANT_COLOR
blend constant
SDL_GPU_BLENDFACTOR_DST_ALPHA
destination alpha
SDL_GPU_BLENDFACTOR_DST_COLOR
destination color
SDL_GPU_BLENDFACTOR_INVALID
SDL_GPU_BLENDFACTOR_ONE
1
SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR
1 - blend constant
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA
1 - destination alpha
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR
1 - destination color
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA
1 - source alpha
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR
1 - source color
SDL_GPU_BLENDFACTOR_SRC_ALPHA
source alpha
SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE
min(source alpha, 1 - destination alpha)
SDL_GPU_BLENDFACTOR_SRC_COLOR
source color
SDL_GPU_BLENDFACTOR_ZERO
0
SDL_GPU_BLENDOP_ADD
(source * source_factor) + (destination * destination_factor)
SDL_GPU_BLENDOP_INVALID
SDL_GPU_BLENDOP_MAX
max(source, destination)
SDL_GPU_BLENDOP_MIN
min(source, destination)
SDL_GPU_BLENDOP_REVERSE_SUBTRACT
(destination * destination_factor) - (source * source_factor)
SDL_GPU_BLENDOP_SUBTRACT
(source * source_factor) - (destination * destination_factor)
SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ
Buffer supports storage reads in the compute stage.
SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE
Buffer supports storage writes in the compute stage.
SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ
Buffer supports storage reads in graphics stages.
SDL_GPU_BUFFERUSAGE_INDEX
Buffer is an index buffer.
SDL_GPU_BUFFERUSAGE_INDIRECT
Buffer is an indirect buffer.
SDL_GPU_BUFFERUSAGE_VERTEX
Buffer is a vertex buffer.
SDL_GPU_COLORCOMPONENT_A
the alpha component
SDL_GPU_COLORCOMPONENT_B
the blue component
SDL_GPU_COLORCOMPONENT_G
the green component
SDL_GPU_COLORCOMPONENT_R
the red component
SDL_GPU_COMPAREOP_ALWAYS
The comparison always evaluates true.
SDL_GPU_COMPAREOP_EQUAL
The comparison evaluates reference == test.
SDL_GPU_COMPAREOP_GREATER
The comparison evaluates reference > test.
SDL_GPU_COMPAREOP_GREATER_OR_EQUAL
The comparison evalutes reference >= test.
SDL_GPU_COMPAREOP_INVALID
SDL_GPU_COMPAREOP_LESS
The comparison evaluates reference < test.
SDL_GPU_COMPAREOP_LESS_OR_EQUAL
The comparison evaluates reference <= test.
SDL_GPU_COMPAREOP_NEVER
The comparison always evaluates false.
SDL_GPU_COMPAREOP_NOT_EQUAL
The comparison evaluates reference != test.
SDL_GPU_CUBEMAPFACE_NEGATIVEX
SDL_GPU_CUBEMAPFACE_NEGATIVEY
SDL_GPU_CUBEMAPFACE_NEGATIVEZ
SDL_GPU_CUBEMAPFACE_POSITIVEX
SDL_GPU_CUBEMAPFACE_POSITIVEY
SDL_GPU_CUBEMAPFACE_POSITIVEZ
SDL_GPU_CULLMODE_BACK
Back-facing triangles are culled.
SDL_GPU_CULLMODE_FRONT
Front-facing triangles are culled.
SDL_GPU_CULLMODE_NONE
No triangles are culled.
SDL_GPU_FILLMODE_FILL
Polygons will be rendered via rasterization.
SDL_GPU_FILLMODE_LINE
Polygon edges will be drawn as line segments.
SDL_GPU_FILTER_LINEAR
Linear filtering.
SDL_GPU_FILTER_NEAREST
Point filtering.
SDL_GPU_FRONTFACE_CLOCKWISE
A triangle with clockwise vertex winding will be considered front-facing.
SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE
A triangle with counter-clockwise vertex winding will be considered front-facing.
SDL_GPU_INDEXELEMENTSIZE_16BIT
The index elements are 16-bit.
SDL_GPU_INDEXELEMENTSIZE_32BIT
The index elements are 32-bit.
SDL_GPU_LOADOP_CLEAR
The contents of the texture will be cleared to a color.
SDL_GPU_LOADOP_DONT_CARE
The previous contents of the texture need not be preserved. The contents will be undefined.
SDL_GPU_LOADOP_LOAD
The previous contents of the texture will be preserved.
SDL_GPU_PRESENTMODE_IMMEDIATE
SDL_GPU_PRESENTMODE_MAILBOX
SDL_GPU_PRESENTMODE_VSYNC
SDL_GPU_PRIMITIVETYPE_LINELIST
A series of separate lines.
SDL_GPU_PRIMITIVETYPE_LINESTRIP
A series of connected lines.
SDL_GPU_PRIMITIVETYPE_POINTLIST
A series of separate points.
SDL_GPU_PRIMITIVETYPE_TRIANGLELIST
A series of separate triangles.
SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP
A series of connected triangles.
SDL_GPU_SAMPLECOUNT_1
No multisampling.
SDL_GPU_SAMPLECOUNT_2
MSAA 2x
SDL_GPU_SAMPLECOUNT_4
MSAA 4x
SDL_GPU_SAMPLECOUNT_8
MSAA 8x
SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE
Specifies that the coordinates will clamp to the 0-1 range.
SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT
Specifies that the coordinates will wrap around mirrored.
SDL_GPU_SAMPLERADDRESSMODE_REPEAT
Specifies that the coordinates will wrap around.
SDL_GPU_SAMPLERMIPMAPMODE_LINEAR
Linear filtering.
SDL_GPU_SAMPLERMIPMAPMODE_NEAREST
Point filtering.
SDL_GPU_SHADERFORMAT_DXBC
DXBC SM5_1 shaders for D3D12.
SDL_GPU_SHADERFORMAT_DXIL
DXIL SM6_0 shaders for D3D12.
SDL_GPU_SHADERFORMAT_INVALID
SDL_GPU_SHADERFORMAT_METALLIB
Precompiled metallib shaders for Metal.
SDL_GPU_SHADERFORMAT_MSL
MSL shaders for Metal.
SDL_GPU_SHADERFORMAT_PRIVATE
Shaders for NDA’d platforms.
SDL_GPU_SHADERFORMAT_SPIRV
SPIR-V shaders for Vulkan.
SDL_GPU_SHADERSTAGE_FRAGMENT
SDL_GPU_SHADERSTAGE_VERTEX
SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP
Decrements the current value and clamps to 0.
SDL_GPU_STENCILOP_DECREMENT_AND_WRAP
Decrements the current value and wraps to the maximum value.
SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP
Increments the current value and clamps to the maximum value.
SDL_GPU_STENCILOP_INCREMENT_AND_WRAP
Increments the current value and wraps back to 0.
SDL_GPU_STENCILOP_INVALID
SDL_GPU_STENCILOP_INVERT
Bitwise-inverts the current value.
SDL_GPU_STENCILOP_KEEP
Keeps the current value.
SDL_GPU_STENCILOP_REPLACE
Sets the value to reference.
SDL_GPU_STENCILOP_ZERO
Sets the value to 0.
SDL_GPU_STOREOP_DONT_CARE
The contents generated during the render pass are not needed and may be discarded. The contents will be undefined.
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.
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.
SDL_GPU_STOREOP_STORE
The contents generated during the render pass will be written to memory.
SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084
SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR
SDL_GPU_SWAPCHAINCOMPOSITION_SDR
SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR
SDL_GPU_TEXTUREFORMAT_A8_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT
SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM
SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM
SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM
SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM
SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM
SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM
SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM
SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM
SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM
SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM
SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT
SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT
SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM
SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_D16_UNORM
SDL_GPU_TEXTUREFORMAT_D24_UNORM
SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT
SDL_GPU_TEXTUREFORMAT_D32_FLOAT
SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT
SDL_GPU_TEXTUREFORMAT_INVALID
SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT
SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM
SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UINT
SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM
SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB
SDL_GPU_TEXTUREFORMAT_R8G8_INT
SDL_GPU_TEXTUREFORMAT_R8G8_SNORM
SDL_GPU_TEXTUREFORMAT_R8G8_UINT
SDL_GPU_TEXTUREFORMAT_R8G8_UNORM
SDL_GPU_TEXTUREFORMAT_R8_INT
SDL_GPU_TEXTUREFORMAT_R8_SNORM
SDL_GPU_TEXTUREFORMAT_R8_UINT
SDL_GPU_TEXTUREFORMAT_R8_UNORM
SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM
SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT
SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT
SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT
SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM
SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT
SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM
SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT
SDL_GPU_TEXTUREFORMAT_R16G16_INT
SDL_GPU_TEXTUREFORMAT_R16G16_SNORM
SDL_GPU_TEXTUREFORMAT_R16G16_UINT
SDL_GPU_TEXTUREFORMAT_R16G16_UNORM
SDL_GPU_TEXTUREFORMAT_R16_FLOAT
SDL_GPU_TEXTUREFORMAT_R16_INT
SDL_GPU_TEXTUREFORMAT_R16_SNORM
SDL_GPU_TEXTUREFORMAT_R16_UINT
SDL_GPU_TEXTUREFORMAT_R16_UNORM
SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT
SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT
SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT
SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT
SDL_GPU_TEXTUREFORMAT_R32G32_INT
SDL_GPU_TEXTUREFORMAT_R32G32_UINT
SDL_GPU_TEXTUREFORMAT_R32_FLOAT
SDL_GPU_TEXTUREFORMAT_R32_INT
SDL_GPU_TEXTUREFORMAT_R32_UINT
SDL_GPU_TEXTURETYPE_2D
The texture is a 2-dimensional image.
SDL_GPU_TEXTURETYPE_2D_ARRAY
The texture is a 2-dimensional array image.
SDL_GPU_TEXTURETYPE_3D
The texture is a 3-dimensional image.
SDL_GPU_TEXTURETYPE_CUBE
The texture is a cube image.
SDL_GPU_TEXTURETYPE_CUBE_ARRAY
The texture is a cube array image.
SDL_GPU_TEXTUREUSAGE_COLOR_TARGET
Texture is a color render target.
SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ
Texture supports storage reads in the compute stage.
SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE
Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE.
SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE
Texture supports storage writes in the compute stage.
SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET
Texture is a depth stencil target.
SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ
Texture supports storage reads in graphics stages.
SDL_GPU_TEXTUREUSAGE_SAMPLER
Texture supports sampling.
SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD
SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD
SDL_GPU_VERTEXELEMENTFORMAT_BYTE2
SDL_GPU_VERTEXELEMENTFORMAT_BYTE4
SDL_GPU_VERTEXELEMENTFORMAT_BYTE2_NORM
SDL_GPU_VERTEXELEMENTFORMAT_BYTE4_NORM
SDL_GPU_VERTEXELEMENTFORMAT_FLOAT
SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2
SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3
SDL_GPU_VERTEXELEMENTFORMAT_FLOAT4
SDL_GPU_VERTEXELEMENTFORMAT_HALF2
SDL_GPU_VERTEXELEMENTFORMAT_HALF4
SDL_GPU_VERTEXELEMENTFORMAT_INT
SDL_GPU_VERTEXELEMENTFORMAT_INT2
SDL_GPU_VERTEXELEMENTFORMAT_INT3
SDL_GPU_VERTEXELEMENTFORMAT_INT4
SDL_GPU_VERTEXELEMENTFORMAT_INVALID
SDL_GPU_VERTEXELEMENTFORMAT_SHORT2
SDL_GPU_VERTEXELEMENTFORMAT_SHORT4
SDL_GPU_VERTEXELEMENTFORMAT_SHORT2_NORM
SDL_GPU_VERTEXELEMENTFORMAT_SHORT4_NORM
SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2
SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4
SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2_NORM
SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM
SDL_GPU_VERTEXELEMENTFORMAT_UINT
SDL_GPU_VERTEXELEMENTFORMAT_UINT2
SDL_GPU_VERTEXELEMENTFORMAT_UINT3
SDL_GPU_VERTEXELEMENTFORMAT_UINT4
SDL_GPU_VERTEXELEMENTFORMAT_USHORT2
SDL_GPU_VERTEXELEMENTFORMAT_USHORT4
SDL_GPU_VERTEXELEMENTFORMAT_USHORT2_NORM
SDL_GPU_VERTEXELEMENTFORMAT_USHORT4_NORM
SDL_GPU_VERTEXINPUTRATE_INSTANCE
Attribute addressing is a function of the instance index.
SDL_GPU_VERTEXINPUTRATE_VERTEX
Attribute addressing is a function of the vertex index.
SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING
SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING
SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING
SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING
SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN
SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING
SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING
SDL_PROP_GPU_SHADER_CREATE_NAME_STRING
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8
SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING
SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING

Functions§

SDL_AcquireGPUCommandBuffer⚠
Acquire a command buffer.
SDL_AcquireGPUSwapchainTexture⚠
Acquire a texture to use in presentation.
SDL_BeginGPUComputePass⚠
Begins a compute pass on a command buffer.
SDL_BeginGPUCopyPass⚠
Begins a copy pass on a command buffer.
SDL_BeginGPURenderPass⚠
Begins a render pass on a command buffer.
SDL_BindGPUComputePipeline⚠
Binds a compute pipeline on a command buffer for use in compute dispatch.
SDL_BindGPUComputeSamplers⚠
Binds texture-sampler pairs for use on the compute shader.
SDL_BindGPUComputeStorageBuffers⚠
Binds storage buffers as readonly for use on the compute pipeline.
SDL_BindGPUComputeStorageTextures⚠
Binds storage textures as readonly for use on the compute pipeline.
SDL_BindGPUFragmentSamplers⚠
Binds texture-sampler pairs for use on the fragment shader.
SDL_BindGPUFragmentStorageBuffers⚠
Binds storage buffers for use on the fragment shader.
SDL_BindGPUFragmentStorageTextures⚠
Binds storage textures for use on the fragment shader.
SDL_BindGPUGraphicsPipeline⚠
Binds a graphics pipeline on a render pass to be used in rendering.
SDL_BindGPUIndexBuffer⚠
Binds an index buffer on a command buffer for use with subsequent draw calls.
SDL_BindGPUVertexBuffers⚠
Binds vertex buffers on a command buffer for use with subsequent draw calls.
SDL_BindGPUVertexSamplers⚠
Binds texture-sampler pairs for use on the vertex shader.
SDL_BindGPUVertexStorageBuffers⚠
Binds storage buffers for use on the vertex shader.
SDL_BindGPUVertexStorageTextures⚠
Binds storage textures for use on the vertex shader.
SDL_BlitGPUTexture⚠
Blits from a source texture region to a destination texture region.
SDL_CalculateGPUTextureFormatSize⚠
Calculate the size in bytes of a texture format with dimensions.
SDL_CancelGPUCommandBuffer⚠
Cancels a command buffer.
SDL_ClaimWindowForGPUDevice⚠
Claims a window, creating a swapchain structure for it.
SDL_CopyGPUBufferToBuffer⚠
Performs a buffer-to-buffer copy.
SDL_CopyGPUTextureToTexture⚠
Performs a texture-to-texture copy.
SDL_CreateGPUBuffer⚠
Creates a buffer object to be used in graphics or compute workflows.
SDL_CreateGPUComputePipeline⚠
Creates a pipeline object to be used in a compute workflow.
SDL_CreateGPUDevice⚠
Creates a GPU context.
SDL_CreateGPUDeviceWithProperties⚠
Creates a GPU context.
SDL_CreateGPUGraphicsPipeline⚠
Creates a pipeline object to be used in a graphics workflow.
SDL_CreateGPUSampler⚠
Creates a sampler object to be used when binding textures in a graphics workflow.
SDL_CreateGPUShader⚠
Creates a shader to be used when creating a graphics pipeline.
SDL_CreateGPUTexture⚠
Creates a texture object to be used in graphics or compute workflows.
SDL_CreateGPUTransferBuffer⚠
Creates a transfer buffer to be used when uploading to or downloading from graphics resources.
SDL_DestroyGPUDevice⚠
Destroys a GPU context previously returned by SDL_CreateGPUDevice.
SDL_DispatchGPUCompute⚠
Dispatches compute work.
SDL_DispatchGPUComputeIndirect⚠
Dispatches compute work with parameters set from a buffer.
SDL_DownloadFromGPUBuffer⚠
Copies data from a buffer to a transfer buffer on the GPU timeline.
SDL_DownloadFromGPUTexture⚠
Copies data from a texture to a transfer buffer on the GPU timeline.
SDL_DrawGPUIndexedPrimitives⚠
Draws data using bound graphics state with an index buffer and instancing enabled.
SDL_DrawGPUIndexedPrimitivesIndirect⚠
Draws data using bound graphics state with an index buffer enabled and with draw parameters set from a buffer.
SDL_DrawGPUPrimitives⚠
Draws data using bound graphics state.
SDL_DrawGPUPrimitivesIndirect⚠
Draws data using bound graphics state and with draw parameters set from a buffer.
SDL_EndGPUComputePass⚠
Ends the current compute pass.
SDL_EndGPUCopyPass⚠
Ends the current copy pass.
SDL_EndGPURenderPass⚠
Ends the given render pass.
SDL_GPUSupportsProperties⚠
Checks for GPU runtime support.
SDL_GPUSupportsShaderFormats⚠
Checks for GPU runtime support.
SDL_GPUTextureFormatTexelBlockSize⚠
Obtains the texel block size for a texture format.
SDL_GPUTextureSupportsFormat⚠
Determines whether a texture format is supported for a given type and usage.
SDL_GPUTextureSupportsSampleCount⚠
Determines if a sample count for a texture format is supported.
SDL_GenerateMipmapsForGPUTexture⚠
Generates mipmaps for the given texture.
SDL_GetGPUDeviceDriver⚠
Returns the name of the backend used to create this GPU context.
SDL_GetGPUDriver⚠
Get the name of a built in GPU driver.
SDL_GetGPUShaderFormats⚠
Returns the supported shader formats for this GPU context.
SDL_GetGPUSwapchainTextureFormat⚠
Obtains the texture format of the swapchain for the given window.
SDL_GetNumGPUDrivers⚠
Get the number of GPU drivers compiled into SDL.
SDL_InsertGPUDebugLabel⚠
Inserts an arbitrary string label into the command buffer callstream.
SDL_MapGPUTransferBuffer⚠
Maps a transfer buffer into application address space.
SDL_PopGPUDebugGroup⚠
Ends the most-recently pushed debug group.
SDL_PushGPUComputeUniformData⚠
Pushes data to a uniform slot on the command buffer.
SDL_PushGPUDebugGroup⚠
Begins a debug group with an arbitary name.
SDL_PushGPUFragmentUniformData⚠
Pushes data to a fragment uniform slot on the command buffer.
SDL_PushGPUVertexUniformData⚠
Pushes data to a vertex uniform slot on the command buffer.
SDL_QueryGPUFence⚠
Checks the status of a fence.
SDL_ReleaseGPUBuffer⚠
Frees the given buffer as soon as it is safe to do so.
SDL_ReleaseGPUComputePipeline⚠
Frees the given compute pipeline as soon as it is safe to do so.
SDL_ReleaseGPUFence⚠
Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence.
SDL_ReleaseGPUGraphicsPipeline⚠
Frees the given graphics pipeline as soon as it is safe to do so.
SDL_ReleaseGPUSampler⚠
Frees the given sampler as soon as it is safe to do so.
SDL_ReleaseGPUShader⚠
Frees the given shader as soon as it is safe to do so.
SDL_ReleaseGPUTexture⚠
Frees the given texture as soon as it is safe to do so.
SDL_ReleaseGPUTransferBuffer⚠
Frees the given transfer buffer as soon as it is safe to do so.
SDL_ReleaseWindowFromGPUDevice⚠
Unclaims a window, destroying its swapchain structure.
SDL_SetGPUAllowedFramesInFlight⚠
Configures the maximum allowed number of frames in flight.
SDL_SetGPUBlendConstants⚠
Sets the current blend constants on a command buffer.
SDL_SetGPUBufferName⚠
Sets an arbitrary string constant to label a buffer.
SDL_SetGPUScissor⚠
Sets the current scissor state on a command buffer.
SDL_SetGPUStencilReference⚠
Sets the current stencil reference value on a command buffer.
SDL_SetGPUSwapchainParameters⚠
Changes the swapchain parameters for the given claimed window.
SDL_SetGPUTextureName⚠
Sets an arbitrary string constant to label a texture.
SDL_SetGPUViewport⚠
Sets the current viewport state on a command buffer.
SDL_SubmitGPUCommandBuffer⚠
Submits a command buffer so its commands can be processed on the GPU.
SDL_SubmitGPUCommandBufferAndAcquireFence⚠
Submits a command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer.
SDL_UnmapGPUTransferBuffer⚠
Unmaps a previously mapped transfer buffer.
SDL_UploadToGPUBuffer⚠
Uploads data from a transfer buffer to a buffer.
SDL_UploadToGPUTexture⚠
Uploads data from a transfer buffer to a texture.
SDL_WaitAndAcquireGPUSwapchainTexture⚠
Blocks the thread until a swapchain texture is available to be acquired, and then acquires it.
SDL_WaitForGPUFences⚠
Blocks the thread until the given fences are signaled.
SDL_WaitForGPUIdle⚠
Blocks the thread until the GPU is completely idle.
SDL_WaitForGPUSwapchain⚠
Blocks the thread until a swapchain texture is available to be acquired.
SDL_WindowSupportsGPUPresentMode⚠
Determines whether a presentation mode is supported by the window.
SDL_WindowSupportsGPUSwapchainComposition⚠
Determines whether a swapchain composition is supported by the window.

Type Aliases§

SDL_GPUBufferUsageFlags
Specifies how a buffer is intended to be used by the client.
SDL_GPUColorComponentFlags
Specifies which color components are written in a graphics pipeline.
SDL_GPUShaderFormat
Specifies the format of shader code.
SDL_GPUTextureUsageFlags
Specifies how a texture is intended to be used by the client.