SDL 3.0
|
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_surface.h>
#include <SDL3/SDL_video.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
Go to the source code of this file.
Typedefs | |
typedef struct SDL_GPUDevice | SDL_GPUDevice |
typedef struct SDL_GPUBuffer | SDL_GPUBuffer |
typedef struct SDL_GPUTransferBuffer | SDL_GPUTransferBuffer |
typedef struct SDL_GPUTexture | SDL_GPUTexture |
typedef struct SDL_GPUSampler | SDL_GPUSampler |
typedef struct SDL_GPUShader | SDL_GPUShader |
typedef struct SDL_GPUComputePipeline | SDL_GPUComputePipeline |
typedef struct SDL_GPUGraphicsPipeline | SDL_GPUGraphicsPipeline |
typedef struct SDL_GPUCommandBuffer | SDL_GPUCommandBuffer |
typedef struct SDL_GPURenderPass | SDL_GPURenderPass |
typedef struct SDL_GPUComputePass | SDL_GPUComputePass |
typedef struct SDL_GPUCopyPass | SDL_GPUCopyPass |
typedef struct SDL_GPUFence | SDL_GPUFence |
typedef Uint32 | SDL_GPUTextureUsageFlags |
typedef Uint32 | SDL_GPUBufferUsageFlags |
typedef Uint32 | SDL_GPUShaderFormat |
typedef Uint8 | SDL_GPUColorComponentFlags |
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) |
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) |
#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) |
#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) |
#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) |
#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) |
#define SDL_GPU_COLORCOMPONENT_A (1u << 3) |
#define SDL_GPU_COLORCOMPONENT_B (1u << 2) |
#define SDL_GPU_COLORCOMPONENT_G (1u << 1) |
#define SDL_GPU_COLORCOMPONENT_R (1u << 0) |
#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) |
#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) |
#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) |
#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) |
#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) |
#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) |
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) |
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) |
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) |
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) |
#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) |
#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) |
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) |
#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" |
#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" |
#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" |
#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" |
#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" |
#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" |
#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" |
#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" |
#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" |
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" |
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" |
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" |
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" |
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" |
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER "SDL.gpu.texture.create.d3d12.clear.stencil" |
#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" |
#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" |
typedef struct SDL_GPUBuffer SDL_GPUBuffer |
An opaque handle representing a buffer.
Used for vertices, indices, indirect draw commands, and general compute data.
typedef Uint32 SDL_GPUBufferUsageFlags |
Specifies how a buffer is intended to be used by the client.
A buffer must have at least one usage flag. Note that some usage flag combinations are invalid.
Unlike textures, READ | WRITE can be used for simultaneous read-write usage. The same data synchronization concerns as textures apply.
If you use a STORAGE flag, the data in the buffer must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
typedef Uint8 SDL_GPUColorComponentFlags |
Specifies which color components are written in a graphics pipeline.
typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer |
An opaque handle representing a command buffer.
Most state is managed via command buffers. When setting state using a command buffer, that state is local to the command buffer.
Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is called. Once the command buffer is submitted, it is no longer valid to use it.
Command buffers are executed in submission order. If you submit command buffer A and then command buffer B all commands in A will begin executing before any command in B begins executing.
In multi-threading scenarios, you should only access a command buffer on the thread you acquired it from.
typedef struct SDL_GPUComputePass SDL_GPUComputePass |
An opaque handle representing a compute pass.
This handle is transient and should not be held or referenced after SDL_EndGPUComputePass is called.
typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline |
An opaque handle representing a compute pipeline.
Used during compute passes.
typedef struct SDL_GPUCopyPass SDL_GPUCopyPass |
An opaque handle representing a copy pass.
This handle is transient and should not be held or referenced after SDL_EndGPUCopyPass is called.
typedef struct SDL_GPUDevice SDL_GPUDevice |
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
Here are some basic tips for maximizing your rendering performance.
In general try to remember the golden rule of performance: doing things is more expensive than not doing things. Don't Touch The Driver!
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.
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:
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.
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. An opaque handle representing the SDL_GPU context.
typedef struct SDL_GPUFence SDL_GPUFence |
An opaque handle representing a fence.
typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline |
An opaque handle representing a graphics pipeline.
Used during render passes.
typedef struct SDL_GPURenderPass SDL_GPURenderPass |
An opaque handle representing a render pass.
This handle is transient and should not be held or referenced after SDL_EndGPURenderPass is called.
typedef struct SDL_GPUSampler SDL_GPUSampler |
An opaque handle representing a sampler.
typedef struct SDL_GPUShader SDL_GPUShader |
An opaque handle representing a compiled shader object.
typedef Uint32 SDL_GPUShaderFormat |
Specifies the format of shader code.
Each format corresponds to a specific backend that accepts it.
typedef struct SDL_GPUTexture SDL_GPUTexture |
An opaque handle representing a texture.
typedef Uint32 SDL_GPUTextureUsageFlags |
Specifies how a texture is intended to be used by the client.
A texture must have at least one usage flag. Note that some usage flag combinations are invalid.
With regards to compute storage usage, READ | WRITE means that you can have shader A that only writes into the texture and shader B that only reads from the texture and bind the same texture to either shader respectively. SIMULTANEOUS means that you can do reads and writes within the same shader or compute pass. It also implies that atomic ops can be used, since those are read-modify-write operations. If you use SIMULTANEOUS, you are responsible for avoiding data races, as there is no data synchronization within a compute pass. Note that SIMULTANEOUS usage is only supported by a limited number of texture formats.
typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer |
An opaque handle representing a transfer buffer.
Used for transferring data to and from the device.
enum SDL_GPUBlendFactor |
Specifies a blending factor to be used when pixels in a render target are blended with existing pixels in the texture.
The source color is the value written by the fragment shader. The destination color is the value currently existing in the texture.
Definition at line 1151 of file SDL_gpu.h.
enum SDL_GPUBlendOp |
Specifies the operator to be used when pixels in a render target are blended with existing pixels in the texture.
The source color is the value written by the fragment shader. The destination color is the value currently existing in the texture.
Definition at line 1130 of file SDL_gpu.h.
enum SDL_GPUCompareOp |
Specifies a comparison operator for depth, stencil and sampler operations.
Definition at line 1085 of file SDL_gpu.h.
enum SDL_GPUCubeMapFace |
Specifies the face of a cube map.
Can be passed in as the layer field in texture-related structs.
Enumerator | |
---|---|
SDL_GPU_CUBEMAPFACE_POSITIVEX | |
SDL_GPU_CUBEMAPFACE_NEGATIVEX | |
SDL_GPU_CUBEMAPFACE_POSITIVEY | |
SDL_GPU_CUBEMAPFACE_NEGATIVEY | |
SDL_GPU_CUBEMAPFACE_POSITIVEZ | |
SDL_GPU_CUBEMAPFACE_NEGATIVEZ |
Definition at line 874 of file SDL_gpu.h.
enum SDL_GPUCullMode |
Specifies the facing direction in which triangle faces will be culled.
Enumerator | |
---|---|
SDL_GPU_CULLMODE_NONE | No triangles are culled. |
SDL_GPU_CULLMODE_FRONT | Front-facing triangles are culled. |
SDL_GPU_CULLMODE_BACK | Back-facing triangles are culled. |
Definition at line 1057 of file SDL_gpu.h.
enum SDL_GPUFillMode |
Specifies the fill mode of the graphics pipeline.
Enumerator | |
---|---|
SDL_GPU_FILLMODE_FILL | Polygons will be rendered via rasterization. |
SDL_GPU_FILLMODE_LINE | Polygon edges will be drawn as line segments. |
Definition at line 1044 of file SDL_gpu.h.
enum SDL_GPUFilter |
Specifies a filter operation used by a sampler.
Enumerator | |
---|---|
SDL_GPU_FILTER_NEAREST | Point filtering. |
SDL_GPU_FILTER_LINEAR | Linear filtering. |
Definition at line 1190 of file SDL_gpu.h.
enum SDL_GPUFrontFace |
Specifies the vertex winding that will cause a triangle to be determined to be front-facing.
Definition at line 1072 of file SDL_gpu.h.
Specifies the size of elements in an index buffer.
Enumerator | |
---|---|
SDL_GPU_INDEXELEMENTSIZE_16BIT | The index elements are 16-bit. |
SDL_GPU_INDEXELEMENTSIZE_32BIT | The index elements are 32-bit. |
Definition at line 585 of file SDL_gpu.h.
enum SDL_GPULoadOp |
Specifies how the contents of a texture attached to a render pass are treated at the beginning of the render pass.
Definition at line 555 of file SDL_gpu.h.
enum SDL_GPUPresentMode |
Specifies the timing that will be used to present swapchain textures to the OS.
VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be supported on certain systems.
It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming the window if you wish to change the present mode to IMMEDIATE or MAILBOX.
Enumerator | |
---|---|
SDL_GPU_PRESENTMODE_VSYNC | |
SDL_GPU_PRESENTMODE_IMMEDIATE | |
SDL_GPU_PRESENTMODE_MAILBOX |
Definition at line 1249 of file SDL_gpu.h.
enum SDL_GPUPrimitiveType |
Specifies the primitive topology of a graphics pipeline.
If you are using POINTLIST you must include a point size output in the vertex shader.
Note that sized point topology is totally unsupported on D3D12. Any size other than 1 will be ignored. In general, you should avoid using point topology for both compatibility and performance reasons. You WILL regret using it.
Definition at line 538 of file SDL_gpu.h.
enum SDL_GPUSampleCount |
Specifies the sample count of a texture.
Used in multisampling. Note that this value only applies when the texture is used as a render target.
Enumerator | |
---|---|
SDL_GPU_SAMPLECOUNT_1 | No multisampling. |
SDL_GPU_SAMPLECOUNT_2 | MSAA 2x |
SDL_GPU_SAMPLECOUNT_4 | MSAA 4x |
SDL_GPU_SAMPLECOUNT_8 | MSAA 8x |
Definition at line 858 of file SDL_gpu.h.
Specifies behavior of texture sampling when the coordinates exceed the 0-1 range.
Definition at line 1217 of file SDL_gpu.h.
Specifies a mipmap mode used by a sampler.
Enumerator | |
---|---|
SDL_GPU_SAMPLERMIPMAPMODE_NEAREST | Point filtering. |
SDL_GPU_SAMPLERMIPMAPMODE_LINEAR | Linear filtering. |
Definition at line 1203 of file SDL_gpu.h.
enum SDL_GPUShaderStage |
Specifies which stage a shader program corresponds to.
Enumerator | |
---|---|
SDL_GPU_SHADERSTAGE_VERTEX | |
SDL_GPU_SHADERSTAGE_FRAGMENT |
Definition at line 933 of file SDL_gpu.h.
enum SDL_GPUStencilOp |
Specifies what happens to a stored stencil value if stencil tests fail or pass.
Definition at line 1106 of file SDL_gpu.h.
enum SDL_GPUStoreOp |
Specifies how the contents of a texture attached to a render pass are treated at the end of the render pass.
Definition at line 570 of file SDL_gpu.h.
Specifies the texture format and colorspace of the swapchain textures.
SDR will always be supported. Other compositions may not be supported on certain systems.
It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after claiming the window if you wish to change the swapchain composition from SDR.
Enumerator | |
---|---|
SDL_GPU_SWAPCHAINCOMPOSITION_SDR | |
SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR | |
SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR | |
SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 |
Definition at line 1282 of file SDL_gpu.h.
enum SDL_GPUTextureFormat |
Specifies the pixel format of a texture.
Texture format support varies depending on driver, hardware, and usage flags. In general, you should use SDL_GPUTextureSupportsFormat to query if a format is supported before using it. However, there are a few guaranteed formats.
FIXME: Check universal support for 32-bit component formats FIXME: Check universal support for SIMULTANEOUS_READ_WRITE
For SAMPLER usage, the following formats are universally supported:
For COLOR_TARGET usage, the following formats are universally supported:
For STORAGE usages, the following formats are universally supported:
For DEPTH_STENCIL_TARGET usage, the following formats are universally supported:
Unless D16_UNORM is sufficient for your purposes, always check which of D24/D32 is supported before creating a depth-stencil texture!
Definition at line 676 of file SDL_gpu.h.
enum SDL_GPUTextureType |
Specifies the type of a texture.
Definition at line 838 of file SDL_gpu.h.
Specifies how a transfer buffer is intended to be used by the client.
Note that mapping and copying FROM an upload transfer buffer or TO a download transfer buffer is undefined behavior.
Enumerator | |
---|---|
SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD | |
SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD |
Definition at line 920 of file SDL_gpu.h.
Specifies the format of a vertex attribute.
Definition at line 965 of file SDL_gpu.h.
Specifies the rate at which vertex attributes are pulled from buffers.
Enumerator | |
---|---|
SDL_GPU_VERTEXINPUTRATE_VERTEX | Attribute addressing is a function of the vertex index. |
SDL_GPU_VERTEXINPUTRATE_INSTANCE | Attribute addressing is a function of the instance index. |
Definition at line 1031 of file SDL_gpu.h.
|
extern |
Acquire a command buffer.
This command buffer is managed by the implementation and should not be freed by the user. The command buffer may only be used on the thread it was acquired on. The command buffer should be submitted on the thread it was acquired on.
It is valid to acquire multiple command buffers on the same thread at once. In fact a common design pattern is to acquire two command buffers per frame where one is dedicated to render and compute passes and the other is dedicated to copy passes and other preparatory work such as generating mipmaps. Interleaving commands between the two command buffers reduces the total amount of passes overall which improves rendering performance.
device | a GPU context. |
|
extern |
Acquire a texture to use in presentation.
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it.
This function will fill the swapchain texture handle with NULL if too many frames are in flight. This is not an error.
If you use this function, it is possible to create a situation where many command buffers are allocated while the rendering context waits for the GPU to catch up, which will cause memory usage to grow. You should use SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing with timing.
The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
command_buffer | a command buffer. |
window | a window that has been claimed. |
swapchain_texture | a pointer filled in with a swapchain texture handle. |
swapchain_texture_width | a pointer filled in with the swapchain texture width, may be NULL. |
swapchain_texture_height | a pointer filled in with the swapchain texture height, may be NULL. |
\threadsafety This function should only be called from the thread that created the window.
|
extern |
Begins a compute pass on a command buffer.
A compute pass is defined by a set of texture subresources and buffers that may be written to by compute pipelines. These textures and buffers must have been created with the COMPUTE_STORAGE_WRITE bit or the COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the texture in the compute pass. All operations related to compute pipelines must take place inside of a compute pass. You must not begin another compute pass, or a render pass or copy pass before ending the compute pass.
A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT implicitly synchronized. This means you may cause data races by both reading and writing a resource region in a compute pass, or by writing multiple times to a resource region. If your compute work depends on reading the completed output from a previous dispatch, you MUST end the current compute pass and begin a new one before you can safely access the data. Otherwise you will receive unexpected results. Reading and writing a texture in the same compute pass is only supported by specific texture formats. Make sure you check the format support!
command_buffer | a command buffer. |
storage_texture_bindings | an array of writeable storage texture binding structs. |
num_storage_texture_bindings | the number of storage textures to bind from the array. |
storage_buffer_bindings | an array of writeable storage buffer binding structs. |
num_storage_buffer_bindings | the number of storage buffers to bind from the array. |
|
extern |
Begins a copy pass on a command buffer.
All operations related to copying to or from buffers or textures take place inside a copy pass. You must not begin another copy pass, or a render pass or compute pass before ending the copy pass.
command_buffer | a command buffer. |
|
extern |
Begins a render pass on a command buffer.
A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.
command_buffer | a command buffer. |
color_target_infos | an array of texture subresources with corresponding clear values and load/store ops. |
num_color_targets | the number of color targets in the color_target_infos array. |
depth_stencil_target_info | a texture subresource with corresponding clear value and load/store ops, may be NULL. |
|
extern |
Binds a compute pipeline on a command buffer for use in compute dispatch.
compute_pass | a compute pass handle. |
compute_pipeline | a compute pipeline to bind. |
|
extern |
Binds texture-sampler pairs for use on the compute shader.
The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
compute_pass | a compute pass handle. |
first_slot | the compute sampler slot to begin binding from. |
texture_sampler_bindings | an array of texture-sampler binding structs. |
num_bindings | the number of texture-sampler bindings to bind from the array. |
|
extern |
Binds storage buffers as readonly for use on the compute pipeline.
These buffers must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
compute_pass | a compute pass handle. |
first_slot | the compute storage buffer slot to begin binding from. |
storage_buffers | an array of storage buffer binding structs. |
num_bindings | the number of storage buffers to bind from the array. |
|
extern |
Binds storage textures as readonly for use on the compute pipeline.
These textures must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
compute_pass | a compute pass handle. |
first_slot | the compute storage texture slot to begin binding from. |
storage_textures | an array of storage textures. |
num_bindings | the number of storage textures to bind from the array. |
|
extern |
Binds texture-sampler pairs for use on the fragment shader.
The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
render_pass | a render pass handle. |
first_slot | the fragment sampler slot to begin binding from. |
texture_sampler_bindings | an array of texture-sampler binding structs. |
num_bindings | the number of texture-sampler pairs to bind from the array. |
|
extern |
Binds storage buffers for use on the fragment shader.
These buffers must have been created with SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
render_pass | a render pass handle. |
first_slot | the fragment storage buffer slot to begin binding from. |
storage_buffers | an array of storage buffers. |
num_bindings | the number of storage buffers to bind from the array. |
|
extern |
Binds storage textures for use on the fragment shader.
These textures must have been created with SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
render_pass | a render pass handle. |
first_slot | the fragment storage texture slot to begin binding from. |
storage_textures | an array of storage textures. |
num_bindings | the number of storage textures to bind from the array. |
|
extern |
Binds a graphics pipeline on a render pass to be used in rendering.
A graphics pipeline must be bound before making any draw calls.
render_pass | a render pass handle. |
graphics_pipeline | the graphics pipeline to bind. |
|
extern |
Binds an index buffer on a command buffer for use with subsequent draw calls.
render_pass | a render pass handle. |
binding | a pointer to a struct containing an index buffer and offset. |
index_element_size | whether the index values in the buffer are 16- or 32-bit. |
|
extern |
Binds vertex buffers on a command buffer for use with subsequent draw calls.
render_pass | a render pass handle. |
first_slot | the vertex buffer slot to begin binding from. |
bindings | an array of SDL_GPUBufferBinding structs containing vertex buffers and offset values. |
num_bindings | the number of bindings in the bindings array. |
|
extern |
Binds texture-sampler pairs for use on the vertex shader.
The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
render_pass | a render pass handle. |
first_slot | the vertex sampler slot to begin binding from. |
texture_sampler_bindings | an array of texture-sampler binding structs. |
num_bindings | the number of texture-sampler pairs to bind from the array. |
|
extern |
Binds storage buffers for use on the vertex shader.
These buffers must have been created with SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
render_pass | a render pass handle. |
first_slot | the vertex storage buffer slot to begin binding from. |
storage_buffers | an array of buffers. |
num_bindings | the number of buffers to bind from the array. |
|
extern |
Binds storage textures for use on the vertex shader.
These textures must have been created with SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().
render_pass | a render pass handle. |
first_slot | the vertex storage texture slot to begin binding from. |
storage_textures | an array of storage textures. |
num_bindings | the number of storage texture to bind from the array. |
|
extern |
Blits from a source texture region to a destination texture region.
This function must not be called inside of any pass.
command_buffer | a command buffer. |
info | the blit info struct containing the blit parameters. |
|
extern |
Calculate the size in bytes of a texture format with dimensions.
format | a texture format. |
width | width in pixels. |
height | height in pixels. |
depth_or_layer_count | depth for 3D textures or layer count otherwise. |
|
extern |
Cancels a command buffer.
None of the enqueued commands are executed.
It is an error to call this function after a swapchain texture has been acquired.
This must be called from the thread the command buffer was acquired on.
You must not reference the command buffer after calling this function.
command_buffer | a command buffer. |
|
extern |
Claims a window, creating a swapchain structure for it.
This must be called before SDL_AcquireGPUSwapchainTexture is called using the window. You should only call this function from the thread that created the window.
The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain parameters, you must call SDL_SetGPUSwapchainParameters after claiming the window.
device | a GPU context. |
window | an SDL_Window. |
\threadsafety This function should only be called from the thread that created the window.
|
extern |
Performs a buffer-to-buffer copy.
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
copy_pass | a copy pass handle. |
source | the buffer and offset to copy from. |
destination | the buffer and offset to copy to. |
size | the length of the buffer to copy. |
cycle | if true, cycles the destination buffer if it is already bound, otherwise overwrites the data. |
|
extern |
Performs a texture-to-texture copy.
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
copy_pass | a copy pass handle. |
source | a source texture region. |
destination | a destination texture region. |
w | the width of the region to copy. |
h | the height of the region to copy. |
d | the depth of the region to copy. |
cycle | if true, cycles the destination texture if the destination texture is bound, otherwise overwrites the data. |
|
extern |
Creates a buffer object to be used in graphics or compute workflows.
The contents of this buffer are undefined until data is written to the buffer.
Note that certain combinations of usage flags are invalid. For example, a buffer cannot have both the VERTEX and INDEX flags.
If you use a STORAGE flag, the data in the buffer must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
For better understanding of underlying concepts and memory management with SDL GPU API, you may refer this blog post There are optional properties that can be provided through props
. These are the supported properties:
SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the buffer to create. |
|
extern |
Creates a pipeline object to be used in a compute workflow.
Shader resource bindings must be authored to follow a particular order depending on the shader format.
For SPIR-V shaders, use the following resource sets:
For DXBC and DXIL shaders, use the following register order:
For MSL/metallib, use the following order:
There are optional properties that can be provided through props
. These are the supported properties:
SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the compute pipeline to create. |
|
extern |
Creates a GPU context.
format_flags | a bitflag indicating which shader formats the app is able to provide. |
debug_mode | enable debug mode properties and validations. |
name | the preferred GPU driver, or NULL to let SDL pick the optimal driver. |
|
extern |
Creates a GPU context.
These are the supported properties:
SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN
: enable debug mode properties and validations, defaults to true.SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN
: enable to prefer energy efficiency over maximum GPU performance, defaults to false.SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING
: the name of the GPU driver to use, if a specific one is desired.These are the current shader format properties:
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN
: The app is able to provide shaders for an NDA platform.SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN
: The app is able to provide SPIR-V shaders if applicable.SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN
: The app is able to provide DXBC shaders if applicableSDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN
: The app is able to provide DXIL shaders if applicable.SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN
: The app is able to provide MSL shaders if applicable.SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN
: The app is able to provide Metal shader libraries if applicable.With the D3D12 renderer:
SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING
: the prefix to use for all vertex semantics, default is "TEXCOORD".props | the properties to use. |
|
extern |
Creates a pipeline object to be used in a graphics workflow.
There are optional properties that can be provided through props
. These are the supported properties:
SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the graphics pipeline to create. |
|
extern |
Creates a sampler object to be used when binding textures in a graphics workflow.
There are optional properties that can be provided through props
. These are the supported properties:
SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the sampler to create. |
|
extern |
Creates a shader to be used when creating a graphics pipeline.
Shader resource bindings must be authored to follow a particular order depending on the shader format.
For SPIR-V shaders, use the following resource sets:
For vertex shaders:
For fragment shaders:
For DXBC and DXIL shaders, use the following register order:
For vertex shaders:
For pixel shaders:
For MSL/metallib, use the following order:
Shader semantics other than system-value semantics do not matter in D3D12 and for ease of use the SDL implementation assumes that non system-value semantics will all be TEXCOORD. If you are using HLSL as the shader source language, your vertex semantics should start at TEXCOORD0 and increment like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic prefix to something other than TEXCOORD you can use SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with SDL_CreateGPUDeviceWithProperties().
There are optional properties that can be provided through props
. These are the supported properties:
SDL_PROP_GPU_SHADER_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the shader to create. |
|
extern |
Creates a texture object to be used in graphics or compute workflows.
The contents of this texture are undefined until data is written to the texture.
Note that certain combinations of usage flags are invalid. For example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags.
If you request a sample count higher than the hardware supports, the implementation will automatically fall back to the highest available sample count.
There are optional properties that can be provided through SDL_GPUTextureCreateInfo's props
. These are the supported properties:
SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT
: (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this red intensity. Defaults to zero.SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT
: (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this green intensity. Defaults to zero.SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT
: (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this blue intensity. Defaults to zero.SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT
: (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture to a color with this alpha intensity. Defaults to zero.SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT
: (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a depth of this value. Defaults to zero.SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER
: (Direct3D 12 only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear the texture to a stencil of this Uint8 value. Defaults to zero.SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the texture to create. |
|
extern |
Creates a transfer buffer to be used when uploading to or downloading from graphics resources.
Download buffers can be particularly expensive to create, so it is good practice to reuse them if data will be downloaded regularly.
There are optional properties that can be provided through props
. These are the supported properties:
SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING
: a name that can be displayed in debugging tools.device | a GPU Context. |
createinfo | a struct describing the state of the transfer buffer to create. |
|
extern |
Destroys a GPU context previously returned by SDL_CreateGPUDevice.
device | a GPU Context to destroy. |
|
extern |
Dispatches compute work.
You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
compute_pass | a compute pass handle. |
groupcount_x | number of local workgroups to dispatch in the X dimension. |
groupcount_y | number of local workgroups to dispatch in the Y dimension. |
groupcount_z | number of local workgroups to dispatch in the Z dimension. |
|
extern |
Dispatches compute work with parameters set from a buffer.
The buffer layout should match the layout of SDL_GPUIndirectDispatchCommand. You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
compute_pass | a compute pass handle. |
buffer | a buffer containing dispatch parameters. |
offset | the offset to start reading from the dispatch buffer. |
|
extern |
Copies data from a buffer to a transfer buffer on the GPU timeline.
This data is not guaranteed to be copied until the command buffer fence is signaled.
copy_pass | a copy pass handle. |
source | the source buffer with offset and size. |
destination | the destination transfer buffer with offset. |
|
extern |
Copies data from a texture to a transfer buffer on the GPU timeline.
This data is not guaranteed to be copied until the command buffer fence is signaled.
copy_pass | a copy pass handle. |
source | the source texture region. |
destination | the destination transfer buffer with image layout information. |
|
extern |
Draws data using bound graphics state with an index buffer and instancing enabled.
You must not call this function before binding a graphics pipeline.
Note that the first_vertex
and first_instance
parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
render_pass | a render pass handle. |
num_indices | the number of indices to draw per instance. |
num_instances | the number of instances to draw. |
first_index | the starting index within the index buffer. |
vertex_offset | value added to vertex index before indexing into the vertex buffer. |
first_instance | the ID of the first instance to draw. |
|
extern |
Draws data using bound graphics state with an index buffer enabled and with draw parameters set from a buffer.
The buffer must consist of tightly-packed draw parameter sets that each match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
render_pass | a render pass handle. |
buffer | a buffer containing draw parameters. |
offset | the offset to start reading from the draw buffer. |
draw_count | the number of draw parameter sets that should be read from the draw buffer. |
|
extern |
Draws data using bound graphics state.
You must not call this function before binding a graphics pipeline.
Note that the first_vertex
and first_instance
parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID); GPU APIs and shader languages do not define these built-in variables consistently, so if your shader depends on them, the only way to keep behavior consistent and portable is to always pass 0 for the correlating parameter in the draw calls.
render_pass | a render pass handle. |
num_vertices | the number of vertices to draw. |
num_instances | the number of instances that will be drawn. |
first_vertex | the index of the first vertex to draw. |
first_instance | the ID of the first instance to draw. |
|
extern |
Draws data using bound graphics state and with draw parameters set from a buffer.
The buffer must consist of tightly-packed draw parameter sets that each match the layout of SDL_GPUIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
render_pass | a render pass handle. |
buffer | a buffer containing draw parameters. |
offset | the offset to start reading from the draw buffer. |
draw_count | the number of draw parameter sets that should be read from the draw buffer. |
|
extern |
Ends the current compute pass.
All bound compute state on the command buffer is unset. The compute pass handle is now invalid.
compute_pass | a compute pass handle. |
|
extern |
Ends the current copy pass.
copy_pass | a copy pass handle. |
|
extern |
Ends the given render pass.
All bound graphics state on the render pass command buffer is unset. The render pass handle is now invalid.
render_pass | a render pass handle. |
|
extern |
Generates mipmaps for the given texture.
This function must not be called inside of any pass.
command_buffer | a command_buffer. |
texture | a texture with more than 1 mip level. |
|
extern |
Returns the name of the backend used to create this GPU context.
device | a GPU context to query. |
|
extern |
Get the name of a built in GPU driver.
The GPU drivers are presented in the order in which they are normally checked during initialization.
The names of drivers are all simple, low-ASCII identifiers, like "vulkan", "metal" or "direct3d12". These never have Unicode characters, and are not meant to be proper names.
index | the index of a GPU driver. |
|
extern |
Returns the supported shader formats for this GPU context.
device | a GPU context to query. |
|
extern |
Obtains the texture format of the swapchain for the given window.
Note that this format can change if the swapchain parameters change.
device | a GPU context. |
window | an SDL_Window that has been claimed. |
|
extern |
Get the number of GPU drivers compiled into SDL.
|
extern |
Checks for GPU runtime support.
props | the properties to use. |
|
extern |
Checks for GPU runtime support.
format_flags | a bitflag indicating which shader formats the app is able to provide. |
name | the preferred GPU driver, or NULL to let SDL pick the optimal driver. |
|
extern |
Obtains the texel block size for a texture format.
format | the texture format you want to know the texel size of. |
|
extern |
Determines whether a texture format is supported for a given type and usage.
device | a GPU context. |
format | the texture format to check. |
type | the type of texture (2D, 3D, Cube). |
usage | a bitmask of all usage scenarios to check. |
|
extern |
Determines if a sample count for a texture format is supported.
device | a GPU context. |
format | the texture format to check. |
sample_count | the sample count to check. |
|
extern |
Inserts an arbitrary string label into the command buffer callstream.
Useful for debugging.
command_buffer | a command buffer. |
text | a UTF-8 string constant to insert as the label. |
|
extern |
Maps a transfer buffer into application address space.
You must unmap the transfer buffer before encoding upload commands. The memory is owned by the graphics driver - do NOT call SDL_free() on the returned pointer.
device | a GPU context. |
transfer_buffer | a transfer buffer. |
cycle | if true, cycles the transfer buffer if it is already bound. |
|
extern |
Ends the most-recently pushed debug group.
command_buffer | a command buffer. |
|
extern |
Pushes data to a uniform slot on the command buffer.
Subsequent draw calls will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
command_buffer | a command buffer. |
slot_index | the uniform slot to push data to. |
data | client data to write. |
length | the length of the data to write. |
|
extern |
Begins a debug group with an arbitary name.
Used for denoting groups of calls when viewing the command buffer callstream in a graphics debugging tool.
Each call to SDL_PushGPUDebugGroup must have a corresponding call to SDL_PopGPUDebugGroup.
On some backends (e.g. Metal), pushing a debug group during a render/blit/compute pass will create a group that is scoped to the native pass rather than the command buffer. For best results, if you push a debug group during a pass, always pop it in the same pass.
command_buffer | a command buffer. |
name | a UTF-8 string constant that names the group. |
|
extern |
Pushes data to a fragment uniform slot on the command buffer.
Subsequent draw calls will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
command_buffer | a command buffer. |
slot_index | the fragment uniform slot to push data to. |
data | client data to write. |
length | the length of the data to write. |
|
extern |
Pushes data to a vertex uniform slot on the command buffer.
Subsequent draw calls will use this uniform data.
The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.
command_buffer | a command buffer. |
slot_index | the vertex uniform slot to push data to. |
data | client data to write. |
length | the length of the data to write. |
|
extern |
Checks the status of a fence.
device | a GPU context. |
fence | a fence. |
|
extern |
Frees the given buffer as soon as it is safe to do so.
You must not reference the buffer after calling this function.
device | a GPU context. |
buffer | a buffer to be destroyed. |
|
extern |
Frees the given compute pipeline as soon as it is safe to do so.
You must not reference the compute pipeline after calling this function.
device | a GPU context. |
compute_pipeline | a compute pipeline to be destroyed. |
|
extern |
Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence.
You must not reference the fence after calling this function.
device | a GPU context. |
fence | a fence. |
|
extern |
Frees the given graphics pipeline as soon as it is safe to do so.
You must not reference the graphics pipeline after calling this function.
device | a GPU context. |
graphics_pipeline | a graphics pipeline to be destroyed. |
|
extern |
Frees the given sampler as soon as it is safe to do so.
You must not reference the sampler after calling this function.
device | a GPU context. |
sampler | a sampler to be destroyed. |
|
extern |
Frees the given shader as soon as it is safe to do so.
You must not reference the shader after calling this function.
device | a GPU context. |
shader | a shader to be destroyed. |
|
extern |
Frees the given texture as soon as it is safe to do so.
You must not reference the texture after calling this function.
device | a GPU context. |
texture | a texture to be destroyed. |
|
extern |
Frees the given transfer buffer as soon as it is safe to do so.
You must not reference the transfer buffer after calling this function.
device | a GPU context. |
transfer_buffer | a transfer buffer to be destroyed. |
|
extern |
Unclaims a window, destroying its swapchain structure.
device | a GPU context. |
window | an SDL_Window that has been claimed. |
|
extern |
Configures the maximum allowed number of frames in flight.
The default value when the device is created is 2. This means that after you have submitted 2 frames for presentation, if the GPU has not finished working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the swapchain texture pointer with NULL, and SDL_WaitAndAcquireGPUSwapchainTexture() will block.
Higher values increase throughput at the expense of visual latency. Lower values decrease visual latency at the expense of throughput.
Note that calling this function will stall and flush the command queue to prevent synchronization issues.
The minimum value of allowed frames in flight is 1, and the maximum is 3.
device | a GPU context. |
allowed_frames_in_flight | the maximum number of frames that can be pending on the GPU. |
|
extern |
Sets the current blend constants on a command buffer.
render_pass | a render pass handle. |
blend_constants | the blend constant color. |
|
extern |
Sets an arbitrary string constant to label a buffer.
You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with SDL_CreateGPUBuffer instead of this function to avoid thread safety issues.
device | a GPU Context. |
buffer | a buffer to attach the name to. |
text | a UTF-8 string constant to mark as the name of the buffer. |
\threadsafety This function is not thread safe, you must make sure the buffer is not simultaneously used by any other thread.
|
extern |
Sets the current scissor state on a command buffer.
render_pass | a render pass handle. |
scissor | the scissor area to set. |
|
extern |
Sets the current stencil reference value on a command buffer.
render_pass | a render pass handle. |
reference | the stencil reference value to set. |
|
extern |
Changes the swapchain parameters for the given claimed window.
This function will fail if the requested present mode or swapchain composition are unsupported by the device. Check if the parameters are supported via SDL_WindowSupportsGPUPresentMode / SDL_WindowSupportsGPUSwapchainComposition prior to calling this function.
SDL_GPU_PRESENTMODE_VSYNC with SDL_GPU_SWAPCHAINCOMPOSITION_SDR are always supported.
device | a GPU context. |
window | an SDL_Window that has been claimed. |
swapchain_composition | the desired composition of the swapchain. |
present_mode | the desired present mode for the swapchain. |
|
extern |
Sets an arbitrary string constant to label a texture.
You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with SDL_CreateGPUTexture instead of this function to avoid thread safety issues.
device | a GPU Context. |
texture | a texture to attach the name to. |
text | a UTF-8 string constant to mark as the name of the texture. |
\threadsafety This function is not thread safe, you must make sure the texture is not simultaneously used by any other thread.
|
extern |
Sets the current viewport state on a command buffer.
render_pass | a render pass handle. |
viewport | the viewport to set. |
|
extern |
Submits a command buffer so its commands can be processed on the GPU.
It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
command_buffer | a command buffer. |
|
extern |
Submits a command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer.
You must release this fence when it is no longer needed or it will cause a leak. It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
command_buffer | a command buffer. |
|
extern |
Unmaps a previously mapped transfer buffer.
device | a GPU context. |
transfer_buffer | a previously mapped transfer buffer. |
|
extern |
Uploads data from a transfer buffer to a buffer.
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
copy_pass | a copy pass handle. |
source | the source transfer buffer with offset. |
destination | the destination buffer with offset and size. |
cycle | if true, cycles the buffer if it is already bound, otherwise overwrites the data. |
|
extern |
Uploads data from a transfer buffer to a texture.
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
You must align the data in the transfer buffer to a multiple of the texel size of the texture format.
copy_pass | a copy pass handle. |
source | the source transfer buffer with image layout information. |
destination | the destination texture region. |
cycle | if true, cycles the texture if the texture is bound, otherwise overwrites the data. |
|
extern |
Blocks the thread until a swapchain texture is available to be acquired, and then acquires it.
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it. It is an error to call SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired.
This function can fill the swapchain texture handle with NULL in certain cases, for example if the window is minimized. This is not an error. You should always make sure to check whether the pointer is NULL before actually using it.
The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
The swapchain texture is write-only and cannot be used as a sampler or for another reading operation.
command_buffer | a command buffer. |
window | a window that has been claimed. |
swapchain_texture | a pointer filled in with a swapchain texture handle. |
swapchain_texture_width | a pointer filled in with the swapchain texture width, may be NULL. |
swapchain_texture_height | a pointer filled in with the swapchain texture height, may be NULL. |
\threadsafety This function should only be called from the thread that created the window.
|
extern |
Blocks the thread until the given fences are signaled.
device | a GPU context. |
wait_all | if 0, wait for any fence to be signaled, if 1, wait for all fences to be signaled. |
fences | an array of fences to wait on. |
num_fences | the number of fences in the fences array. |
|
extern |
Blocks the thread until the GPU is completely idle.
device | a GPU context. |
|
extern |
Blocks the thread until a swapchain texture is available to be acquired.
device | a GPU context. |
window | a window that has been claimed. |
\threadsafety This function should only be called from the thread that created the window.
|
extern |
Determines whether a presentation mode is supported by the window.
The window must be claimed before calling this function.
device | a GPU context. |
window | an SDL_Window. |
present_mode | the presentation mode to check. |
|
extern |
Determines whether a swapchain composition is supported by the window.
The window must be claimed before calling this function.
device | a GPU context. |
window | an SDL_Window. |
swapchain_composition | the swapchain composition to check. |