Documentation

Checks for GPU runtime support.

Returns

true if supported, false otherwise.

See also

sDL_CreateGPUDevice

C declaration

SDL_GPUSupportsShaderFormats, defined at SDL3/SDL_gpu.h 2213:34

Since: 3.2.0

Checks for GPU runtime support.

Returns

true if supported, false otherwise.

See also

sDL_CreateGPUDeviceWithProperties

C declaration

SDL_GPUSupportsProperties, defined at SDL3/SDL_gpu.h 2227:34

Since: 3.2.0

Creates a GPU context.

The GPU driver name can be one of the following:

• "vulkan": Vulkan
• "direct3d12": D3D12
• "metal": Metal
• NULL: let SDL pick the optimal driver

Returns

a GPU context on success or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CreateGPUDeviceWithProperties, sDL_GetGPUShaderFormats, sDL_GetGPUDeviceDriver, sDL_DestroyGPUDevice, sDL_GPUSupportsShaderFormats

C declaration

SDL_CreateGPUDevice, defined at SDL3/SDL_gpu.h 2256:45

Since: 3.2.0

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_VERBOSE_BOOLEAN: enable to automatically log useful debug information on device creation, defaults to true.
• sDL_PROP_GPU_DEVICE_CREATE_NAME_STRING: the name of the GPU driver to use, if a specific one is desired.
• sDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN: Enable Vulkan device feature shaderClipDistance. If disabled, clip distances are not supported in shader code: gl_ClipDistance[] built-ins of GLSL, SV_ClipDistance0/1 semantics of HLSL and [[clip_distance]] attribute of Metal. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
• sDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN: Enable Vulkan device feature depthClamp. If disabled, there is no depth clamp support and enable_depth_clip in SDL_GPURasterizerState must always be set to true. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
• sDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN: Enable Vulkan device feature drawIndirectFirstInstance. If disabled, the argument first_instance of SDL_GPUIndirectDrawCommand must be set to zero. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
• sDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN: Enable Vulkan device feature samplerAnisotropy. If disabled, enable_anisotropy of SDL_GPUSamplerCreateInfo must be set to false. Disabling optional features allows the application to run on some older Android devices. Defaults to true.

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 applicable
• sDL_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 backend:

• sDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING: the prefix to use for all vertex semantics, default is "TEXCOORD".
• sDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN: By default, Resourcing Binding Tier 2 is required for D3D12 support. However, an application can set this property to true to enable Tier 1 support, if (and only if) the application uses 8 or fewer storage resources across all shader stages. As of writing, this property is useful for targeting Intel Haswell and Broadwell GPUs; other hardware either supports Tier 2 Resource Binding or does not support D3D12 in any capacity. Defaults to false.
• sDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_VERSION_NUMBER: Certain feature checks are only possible on Windows 11 by default. By setting this alongside sDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_PATH_STRING and vendoring D3D12Core.dll from the D3D12 Agility SDK, you can make those feature checks possible on older platforms. The version you provide must match the one given in the DLL.
• sDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_PATH_STRING: Certain feature checks are only possible on Windows 11 by default. By setting this alongside sDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_VERSION_NUMBER and vendoring D3D12Core.dll from the D3D12 Agility SDK, you can make those feature checks possible on older platforms. The path you provide must be relative to the executable path of your app. Be sure not to put the DLL in the same directory as the exe; Microsoft strongly advises against this!

With the Vulkan backend:

• sDL_PROP_GPU_DEVICE_CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN: By default, Vulkan device enumeration includes drivers of all types, including software renderers (for example, the Lavapipe Mesa driver). This can be useful if your application requires SDL_GPU, but if you can provide your own fallback renderer (for example, an OpenGL renderer) this property can be set to true. Defaults to false.
• sDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER: a pointer to an SDL_GPUVulkanOptions structure to be processed during device creation. This allows configuring a variety of Vulkan-specific options such as increasing the API version and opting into extensions aside from the minimal set SDL requires.

With the Metal backend: - sDL_PROP_GPU_DEVICE_CREATE_METAL_ALLOW_MACFAMILY1_BOOLEAN: By default, macOS support requires what Apple calls "MTLGPUFamilyMac2" hardware or newer. However, an application can set this property to true to enable support for "MTLGPUFamilyMac1" hardware, if (and only if) the application does not write to sRGB textures. (For history's sake: MacFamily1 also does not support indirect command buffers, MSAA depth resolve, and stencil resolve/feedback, but these are not exposed features in SDL_GPU.)

Returns

a GPU context on success or NULL on failure; call SDL_GetError() for more information.

See also

sDL_GetGPUShaderFormats, sDL_GetGPUDeviceDriver, sDL_DestroyGPUDevice, sDL_GPUSupportsProperties

C declaration

SDL_CreateGPUDeviceWithProperties, defined at SDL3/SDL_gpu.h 2373:45

Since: 3.2.0

Destroys a GPU context previously returned by SDL_CreateGPUDevice.

See also

sDL_CreateGPUDevice

C declaration

SDL_DestroyGPUDevice, defined at SDL3/SDL_gpu.h 2435:34

Since: 3.2.0

Get the number of GPU drivers compiled into SDL.

Returns

the number of built in GPU drivers.

See also

sDL_GetGPUDriver

C declaration

SDL_GetNumGPUDrivers, defined at SDL3/SDL_gpu.h 2446:33

Since: 3.2.0

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.

Returns

the name of the GPU driver with the given index.

See also

sDL_GetNumGPUDrivers

C declaration

SDL_GetGPUDriver, defined at SDL3/SDL_gpu.h 2465:42

Since: 3.2.0

Returns the name of the backend used to create this GPU context.

Returns

the name of the device's driver, or NULL on error.

C declaration

SDL_GetGPUDeviceDriver, defined at SDL3/SDL_gpu.h 2475:42

Since: 3.2.0

Returns the supported shader formats for this GPU context.

Returns

a bitflag indicating which shader formats the driver is able to consume.

C declaration

SDL_GetGPUShaderFormats, defined at SDL3/SDL_gpu.h 2486:49

Since: 3.2.0

Get the properties associated with a GPU device.

All properties are optional and may differ between GPU backends and SDL versions.

The following properties are provided by SDL:

sDL_PROP_GPU_DEVICE_NAME_STRING: Contains the name of the underlying device as reported by the system driver. This string has no standardized format, is highly inconsistent between hardware devices and drivers, and is able to change at any time. Do not attempt to parse this string as it is bound to fail at some point in the future when system drivers are updated, new hardware devices are introduced, or when SDL adds new GPU backends or modifies existing ones.

Strings that have been found in the wild include:

• GTX 970
• GeForce GTX 970
• NVIDIA GeForce GTX 970
• Microsoft Direct3D12 (NVIDIA GeForce GTX 970)
• NVIDIA Graphics Device
• GeForce GPU
• P106-100
• AMD 15D8:C9
• AMD Custom GPU 0405
• AMD Radeon (TM) Graphics
• ASUS Radeon RX 470 Series
• Intel(R) Arc(tm) A380 Graphics (DG2)
• Virtio-GPU Venus (NVIDIA TITAN V)
• SwiftShader Device (LLVM 16.0.0)
• llvmpipe (LLVM 15.0.4, 256 bits)
• Microsoft Basic Render Driver
• unknown device

The above list shows that the same device can have different formats, the vendor name may or may not appear in the string, the included vendor name may not be the vendor of the chipset on the device, some manufacturers include pseudo-legal marks while others don't, some devices may not use a marketing name in the string, the device string may be wrapped by the name of a translation interface, the device may be emulated in software, or the string may contain generic text that does not identify the device at all.

sDL_PROP_GPU_DEVICE_DRIVER_NAME_STRING: Contains the self-reported name of the underlying system driver.

Strings that have been found in the wild include:

• Intel Corporation
• Intel open-source Mesa driver
• Qualcomm Technologies Inc. Adreno Vulkan Driver
• MoltenVK
• Mali-G715
• venus

sDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING: Contains the self-reported version of the underlying system driver. This is a relatively short version string in an unspecified format. If SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING is available then that property should be preferred over this one as it may contain additional information that is useful for identifying the exact driver version used.

Strings that have been found in the wild include:

• 53.0.0
• 0.405.2463
• 32.0.15.6614

sDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING: Contains the detailed version information of the underlying system driver as reported by the driver. This is an arbitrary string with no standardized format and it may contain newlines. This property should be preferred over SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING if it is available as it usually contains the same information but in a format that is easier to read.

Strings that have been found in the wild include:

• 101.6559
• 1.2.11
• Mesa 21.2.2 (LLVM 12.0.1)
• Mesa 22.2.0-devel (git-f226222 2022-04-14 impish-oibaf-ppa)
• v1.r53p0-00eac0.824c4f31403fb1fbf8ee1042422c2129

This string has also been observed to be a multiline string (which has a trailing newline):

    Driver Build: 85da404, I46ff5fc46f, 1606794520
    Date: 11/30/20
    Compiler Version: EV031.31.04.01
    Driver Branch: promo490_3_Google
    

Returns

a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGPUDeviceProperties, defined at SDL3/SDL_gpu.h 2590:46

Since: 3.4.0

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:

• 0: Sampled textures, followed by read-only storage textures, followed by read-only storage buffers
• 1: Read-write storage textures, followed by read-write storage buffers
• 2: Uniform buffers

For DXBC and DXIL shaders, use the following register order:

• (t[n], space0): Sampled textures, followed by read-only storage textures, followed by read-only storage buffers
• (u[n], space1): Read-write storage textures, followed by read-write storage buffers
• (b[n], space2): Uniform buffers

For MSL/metallib, use the following order:

• [[buffer]]: Uniform buffers, followed by read-only storage buffers, followed by read-write storage buffers
• [[texture]]: Sampled textures, followed by read-only storage textures, followed by read-write storage textures

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.

Returns

a compute pipeline object on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_BindGPUComputePipeline, sDL_ReleaseGPUComputePipeline

C declaration

SDL_CreateGPUComputePipeline, defined at SDL3/SDL_gpu.h 2645:54

Since: 3.2.0

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.

Returns

a graphics pipeline object on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CreateGPUShader, sDL_BindGPUGraphicsPipeline, sDL_ReleaseGPUGraphicsPipeline

C declaration

SDL_CreateGPUGraphicsPipeline, defined at SDL3/SDL_gpu.h 2672:55

Since: 3.2.0

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.

Returns

a sampler object on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_BindGPUVertexSamplers, sDL_BindGPUFragmentSamplers, sDL_ReleaseGPUSampler

C declaration

SDL_CreateGPUSampler, defined at SDL3/SDL_gpu.h 2699:46

Since: 3.2.0

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:

• 0: Sampled textures, followed by storage textures, followed by storage buffers
• 1: Uniform buffers

For fragment shaders:

• 2: Sampled textures, followed by storage textures, followed by storage buffers
• 3: Uniform buffers

For DXBC and DXIL shaders, use the following register order:

For vertex shaders:

• (t[n], space0): Sampled textures, followed by storage textures, followed by storage buffers
• (s[n], space0): Samplers with indices corresponding to the sampled textures
• (b[n], space1): Uniform buffers

For pixel shaders:

• (t[n], space2): Sampled textures, followed by storage textures, followed by storage buffers
• (s[n], space2): Samplers with indices corresponding to the sampled textures
• (b[n], space3): Uniform buffers

For MSL/metallib, use the following order:

• [[texture]]: Sampled textures, followed by storage textures
• [[sampler]]: Samplers with indices corresponding to the sampled textures
• [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. Rather than manually authoring vertex buffer indices, use the [[stage_in]] attribute which will automatically use the vertex input information from the SDL_GPUGraphicsPipeline.

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.

Returns

a shader object on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CreateGPUGraphicsPipeline, sDL_ReleaseGPUShader

C declaration

SDL_CreateGPUShader, defined at SDL3/SDL_gpu.h 2778:45

Since: 3.2.0

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, either via SDL_UploadToGPUTexture or by performing a render or compute pass with this texture as a target.

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.

Returns

a texture object on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_UploadToGPUTexture, sDL_DownloadFromGPUTexture, sDL_BeginGPURenderPass, sDL_BeginGPUComputePass, sDL_BindGPUVertexSamplers, sDL_BindGPUVertexStorageTextures, sDL_BindGPUFragmentSamplers, sDL_BindGPUFragmentStorageTextures, sDL_BindGPUComputeStorageTextures, sDL_BlitGPUTexture, sDL_ReleaseGPUTexture, sDL_GPUTextureSupportsFormat

C declaration

SDL_CreateGPUTexture, defined at SDL3/SDL_gpu.h 2842:46

Since: 3.2.0

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.

Returns

a buffer object on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_UploadToGPUBuffer, sDL_DownloadFromGPUBuffer, sDL_CopyGPUBufferToBuffer, sDL_BindGPUVertexBuffers, sDL_BindGPUIndexBuffer, sDL_BindGPUVertexStorageBuffers, sDL_BindGPUFragmentStorageBuffers, sDL_DrawGPUPrimitivesIndirect, sDL_DrawGPUIndexedPrimitivesIndirect, sDL_BindGPUComputeStorageBuffers, sDL_DispatchGPUComputeIndirect, sDL_ReleaseGPUBuffer

C declaration

SDL_CreateGPUBuffer, defined at SDL3/SDL_gpu.h 2898:45

Since: 3.2.0

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.

Returns

a transfer buffer on success, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_UploadToGPUBuffer, sDL_DownloadFromGPUBuffer, sDL_UploadToGPUTexture, sDL_DownloadFromGPUTexture, sDL_ReleaseGPUTransferBuffer

C declaration

SDL_CreateGPUTransferBuffer, defined at SDL3/SDL_gpu.h 2931:53

Since: 3.2.0

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.

Thread safety

This function is not thread safe, you must make sure the buffer is not simultaneously used by any other thread.

See also

sDL_CreateGPUBuffer

C declaration

SDL_SetGPUBufferName, defined at SDL3/SDL_gpu.h 2956:34

Since: 3.2.0

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.

Thread safety

This function is not thread safe, you must make sure the texture is not simultaneously used by any other thread.

See also

sDL_CreateGPUTexture

C declaration

SDL_SetGPUTextureName, defined at SDL3/SDL_gpu.h 2979:34

Since: 3.2.0

Inserts an arbitrary string label into the command buffer callstream.

Useful for debugging.

On Direct3D 12, using SDL_InsertGPUDebugLabel requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.

C declaration

SDL_InsertGPUDebugLabel, defined at SDL3/SDL_gpu.h 3000:34

Since: 3.2.0

Begins a debug group with an arbitrary 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 Direct3D 12, using SDL_PushGPUDebugGroup requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.

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.

See also

sDL_PopGPUDebugGroup

C declaration

SDL_PushGPUDebugGroup, defined at SDL3/SDL_gpu.h 3030:34

Since: 3.2.0

Ends the most-recently pushed debug group.

On Direct3D 12, using SDL_PopGPUDebugGroup requires WinPixEventRuntime.dll to be in your PATH or in the same directory as your executable. See here for instructions on how to obtain it.

See also

sDL_PushGPUDebugGroup

C declaration

SDL_PopGPUDebugGroup, defined at SDL3/SDL_gpu.h 3048:34

Since: 3.2.0

Frees the given texture as soon as it is safe to do so.

You must not reference the texture after calling this function.

C declaration

SDL_ReleaseGPUTexture, defined at SDL3/SDL_gpu.h 3063:34

Since: 3.2.0

Frees the given sampler as soon as it is safe to do so.

You must not reference the sampler after calling this function.

C declaration

SDL_ReleaseGPUSampler, defined at SDL3/SDL_gpu.h 3077:34

Since: 3.2.0

Frees the given buffer as soon as it is safe to do so.

You must not reference the buffer after calling this function.

C declaration

SDL_ReleaseGPUBuffer, defined at SDL3/SDL_gpu.h 3091:34

Since: 3.2.0

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.

C declaration

SDL_ReleaseGPUTransferBuffer, defined at SDL3/SDL_gpu.h 3105:34

Since: 3.2.0

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.

C declaration

SDL_ReleaseGPUComputePipeline, defined at SDL3/SDL_gpu.h 3119:34

Since: 3.2.0

Frees the given shader as soon as it is safe to do so.

You must not reference the shader after calling this function.

C declaration

SDL_ReleaseGPUShader, defined at SDL3/SDL_gpu.h 3133:34

Since: 3.2.0

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.

C declaration

SDL_ReleaseGPUGraphicsPipeline, defined at SDL3/SDL_gpu.h 3147:34

Since: 3.2.0

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.

Returns

a command buffer, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_SubmitGPUCommandBuffer, sDL_SubmitGPUCommandBufferAndAcquireFence

C declaration

SDL_AcquireGPUCommandBuffer, defined at SDL3/SDL_gpu.h 3175:52

Since: 3.2.0

Pushes data to a vertex uniform slot on the command buffer.

Subsequent draw calls in this command buffer 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.

For detailed information about accessing uniform data from a shader, please refer to SDL_CreateGPUShader.

C declaration

SDL_PushGPUVertexUniformData, defined at SDL3/SDL_gpu.h 3199:34

Since: 3.2.0

Pushes data to a fragment uniform slot on the command buffer.

Subsequent draw calls in this command buffer 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.

C declaration

SDL_PushGPUFragmentUniformData, defined at SDL3/SDL_gpu.h 3221:34

Since: 3.2.0

Pushes data to a uniform slot on the command buffer.

Subsequent draw calls in this command buffer 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.

C declaration

SDL_PushGPUComputeUniformData, defined at SDL3/SDL_gpu.h 3243:34

Since: 3.2.0

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.

Using SDL_GPU_LOADOP_LOAD before any contents have been written to the texture subresource will result in undefined behavior. SDL_GPU_LOADOP_CLEAR will set the contents of the texture subresource to a single value before any rendering is performed. It's fine to do an empty render pass using SDL_GPU_STOREOP_STORE to clear a texture, but in general it's better to think of clearing not as an independent operation but as something that's done as the beginning of a render pass.

Returns

a render pass handle.

See also

sDL_EndGPURenderPass

C declaration

SDL_BeginGPURenderPass, defined at SDL3/SDL_gpu.h 3284:49

Since: 3.2.0

Binds a graphics pipeline on a render pass to be used in rendering.

A graphics pipeline must be bound before making any draw calls.

C declaration

SDL_BindGPUGraphicsPipeline, defined at SDL3/SDL_gpu.h 3300:34

Since: 3.2.0

Sets the current viewport state on a command buffer.

C declaration

SDL_SetGPUViewport, defined at SDL3/SDL_gpu.h 3312:34

Since: 3.2.0

Sets the current scissor state on a command buffer.

C declaration

SDL_SetGPUScissor, defined at SDL3/SDL_gpu.h 3324:34

Since: 3.2.0

Sets the current blend constants on a command buffer.

See also

SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR

C declaration

SDL_SetGPUBlendConstants, defined at SDL3/SDL_gpu.h 3339:34

Since: 3.2.0

Sets the current stencil reference value on a command buffer.

C declaration

SDL_SetGPUStencilReference, defined at SDL3/SDL_gpu.h 3351:34

Since: 3.2.0

Binds vertex buffers on a command buffer for use with subsequent draw calls.

C declaration

SDL_BindGPUVertexBuffers, defined at SDL3/SDL_gpu.h 3367:34

Since: 3.2.0

Binds an index buffer on a command buffer for use with subsequent draw calls.

C declaration

SDL_BindGPUIndexBuffer, defined at SDL3/SDL_gpu.h 3384:34

Since: 3.2.0

Binds texture-sampler pairs for use on the vertex shader.

The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.

The textures being bound must have a matching type declared in the shader (2D, 3D, etc.). Multisample textures are not allowed.

Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().

See also

sDL_CreateGPUShader

C declaration

SDL_BindGPUVertexSamplers, defined at SDL3/SDL_gpu.h 3411:34

Since: 3.2.0

Binds storage textures for use on the vertex shader.

These textures must have been created with SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.

The textures being bound must have a matching type declared in the shader (2D, 3D, 2DMS, etc.)

Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().

See also

sDL_CreateGPUShader

C declaration

SDL_BindGPUVertexStorageTextures, defined at SDL3/SDL_gpu.h 3438:34

Since: 3.2.0

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().

See also

sDL_CreateGPUShader

C declaration

SDL_BindGPUVertexStorageBuffers, defined at SDL3/SDL_gpu.h 3462:34

Since: 3.2.0

Binds texture-sampler pairs for use on the fragment shader.

The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.

The textures being bound must have a matching type declared in the shader (2D, 3D, etc.). Multisample textures are not allowed.

Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().

See also

sDL_CreateGPUShader

C declaration

SDL_BindGPUFragmentSamplers, defined at SDL3/SDL_gpu.h 3490:34

Since: 3.2.0

Binds storage textures for use on the fragment shader.

These textures must have been created with SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.

The textures being bound must have a matching type declared in the shader (2D, 3D, 2DMS, etc.)

Be sure your shader is set up according to the requirements documented in SDL_CreateGPUShader().

See also

sDL_CreateGPUShader

C declaration

SDL_BindGPUFragmentStorageTextures, defined at SDL3/SDL_gpu.h 3517:34

Since: 3.2.0

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().

See also

sDL_CreateGPUShader

C declaration

SDL_BindGPUFragmentStorageBuffers, defined at SDL3/SDL_gpu.h 3541:34

Since: 3.2.0

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.

C declaration

SDL_DrawGPUIndexedPrimitives, defined at SDL3/SDL_gpu.h 3572:34

Since: 3.2.0

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.

C declaration

SDL_DrawGPUPrimitives, defined at SDL3/SDL_gpu.h 3600:34

Since: 3.2.0

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.

C declaration

SDL_DrawGPUPrimitivesIndirect, defined at SDL3/SDL_gpu.h 3623:34

Since: 3.2.0

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.

C declaration

SDL_DrawGPUIndexedPrimitivesIndirect, defined at SDL3/SDL_gpu.h 3645:34

Since: 3.2.0

Ends the given render pass.

All bound graphics state on the render pass command buffer is unset. The render pass handle is now invalid.

C declaration

SDL_EndGPURenderPass, defined at SDL3/SDL_gpu.h 3661:34

Since: 3.2.0

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!

Returns

a compute pass handle.

See also

sDL_EndGPUComputePass

C declaration

SDL_BeginGPUComputePass, defined at SDL3/SDL_gpu.h 3703:50

Since: 3.2.0

Binds a compute pipeline on a command buffer for use in compute dispatch.

C declaration

SDL_BindGPUComputePipeline, defined at SDL3/SDL_gpu.h 3718:34

Since: 3.2.0

Binds texture-sampler pairs for use on the compute shader.

The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.

The textures being bound must have a matching type declared in the shader (2D, 3D, etc.). Multisample textures are not allowed.

Be sure your shader is set up according to the requirements documented in SDL_CreateGPUComputePipeline().

See also

sDL_CreateGPUComputePipeline

C declaration

SDL_BindGPUComputeSamplers, defined at SDL3/SDL_gpu.h 3744:34

Since: 3.2.0

Binds storage textures as readonly for use on the compute pipeline.

These textures must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.

The textures being bound must have a matching type declared in the shader (2D, 3D, 2DMS, etc.)

Be sure your shader is set up according to the requirements documented in SDL_CreateGPUComputePipeline().

See also

sDL_CreateGPUComputePipeline

C declaration

SDL_BindGPUComputeStorageTextures, defined at SDL3/SDL_gpu.h 3771:34

Since: 3.2.0

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_CreateGPUComputePipeline().

See also

sDL_CreateGPUComputePipeline

C declaration

SDL_BindGPUComputeStorageBuffers, defined at SDL3/SDL_gpu.h 3795:34

Since: 3.2.0

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.

C declaration

SDL_DispatchGPUCompute, defined at SDL3/SDL_gpu.h 3821:34

Since: 3.2.0

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.

C declaration

SDL_DispatchGPUComputeIndirect, defined at SDL3/SDL_gpu.h 3845:34

Since: 3.2.0

Ends the current compute pass.

All bound compute state on the command buffer is unset. The compute pass handle is now invalid.

C declaration

SDL_EndGPUComputePass, defined at SDL3/SDL_gpu.h 3860:34

Since: 3.2.0

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.

Returns

the address of the mapped transfer buffer memory, or NULL on failure; call SDL_GetError() for more information.

C declaration

SDL_MapGPUTransferBuffer, defined at SDL3/SDL_gpu.h 3880:36

Since: 3.2.0

Unmaps a previously mapped transfer buffer.

C declaration

SDL_UnmapGPUTransferBuffer, defined at SDL3/SDL_gpu.h 3893:34

Since: 3.2.0

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.

Returns

a copy pass handle.

See also

sDL_EndGPUCopyPass

C declaration

SDL_BeginGPUCopyPass, defined at SDL3/SDL_gpu.h 3913:47

Since: 3.2.0

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.

C declaration

SDL_UploadToGPUTexture, defined at SDL3/SDL_gpu.h 3933:34

Since: 3.2.0

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.

C declaration

SDL_UploadToGPUBuffer, defined at SDL3/SDL_gpu.h 3953:34

Since: 3.2.0

Performs a texture-to-texture copy.

This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.

This function does not support copying between depth and color textures. For those, copy the texture to a buffer and then to the destination texture.

C declaration

SDL_CopyGPUTextureToTexture, defined at SDL3/SDL_gpu.h 3980:34

Since: 3.2.0

Performs a buffer-to-buffer copy.

This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.

C declaration

SDL_CopyGPUBufferToBuffer, defined at SDL3/SDL_gpu.h 4004:34

Since: 3.2.0

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.

C declaration

SDL_DownloadFromGPUTexture, defined at SDL3/SDL_gpu.h 4024:34

Since: 3.2.0

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.

C declaration

SDL_DownloadFromGPUBuffer, defined at SDL3/SDL_gpu.h 4041:34

Since: 3.2.0

Ends the current copy pass.

C declaration

SDL_EndGPUCopyPass, defined at SDL3/SDL_gpu.h 4053:34

Since: 3.2.0

Generates mipmaps for the given texture.

This function must not be called inside of any pass.

C declaration

SDL_GenerateMipmapsForGPUTexture, defined at SDL3/SDL_gpu.h 4066:34

Since: 3.2.0

Blits from a source texture region to a destination texture region.

This function must not be called inside of any pass.

C declaration

SDL_BlitGPUTexture, defined at SDL3/SDL_gpu.h 4080:34

Since: 3.2.0

Determines whether a swapchain composition is supported by the window.

The window must be claimed before calling this function.

Returns

true if supported, false if unsupported.

See also

sDL_ClaimWindowForGPUDevice

C declaration

SDL_WindowSupportsGPUSwapchainComposition, defined at SDL3/SDL_gpu.h 4100:34

Since: 3.2.0

Determines whether a presentation mode is supported by the window.

The window must be claimed before calling this function.

Returns

true if supported, false if unsupported.

See also

sDL_ClaimWindowForGPUDevice

C declaration

SDL_WindowSupportsGPUPresentMode, defined at SDL3/SDL_gpu.h 4119:34

Since: 3.2.0

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.

Returns

true on success, or false on failure; call SDL_GetError() for more information.

Thread safety

This function should only be called from the thread that created the window.

See also

sDL_WaitAndAcquireGPUSwapchainTexture, sDL_ReleaseWindowFromGPUDevice, sDL_WindowSupportsGPUPresentMode, sDL_WindowSupportsGPUSwapchainComposition

C declaration

SDL_ClaimWindowForGPUDevice, defined at SDL3/SDL_gpu.h 4151:34

Since: 3.2.0

Unclaims a window, destroying its swapchain structure.

See also

sDL_ClaimWindowForGPUDevice

C declaration

SDL_ReleaseWindowFromGPUDevice, defined at SDL3/SDL_gpu.h 4165:34

Since: 3.2.0

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 is always supported.

Returns

true if successful, false on error; call SDL_GetError() for more information.

See also

sDL_WindowSupportsGPUPresentMode, sDL_WindowSupportsGPUSwapchainComposition

C declaration

SDL_SetGPUSwapchainParameters, defined at SDL3/SDL_gpu.h 4192:34

Since: 3.2.0

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.

Returns

true if successful, false on error; call SDL_GetError() for more information.

C declaration

SDL_SetGPUAllowedFramesInFlight, defined at SDL3/SDL_gpu.h 4223:34

Since: 3.2.0

Obtains the texture format of the swapchain for the given window.

Note that this format can change if the swapchain parameters change.

Returns

the texture format of the swapchain.

C declaration

SDL_GetGPUSwapchainTextureFormat, defined at SDL3/SDL_gpu.h 4238:50

Since: 3.2.0

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. This NULL pointer should not be passed back into SDL. Instead, it should be considered as an indication to wait until the swapchain is available.

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.

Returns

true on success, false on error; call SDL_GetError() for more information.

Thread safety

This function should only be called from the thread that created the window.

See also

sDL_ClaimWindowForGPUDevice, sDL_SubmitGPUCommandBuffer, sDL_SubmitGPUCommandBufferAndAcquireFence, sDL_CancelGPUCommandBuffer, SDL_GetWindowSizeInPixels, sDL_WaitForGPUSwapchain, sDL_WaitAndAcquireGPUSwapchainTexture, sDL_SetGPUAllowedFramesInFlight

C declaration

SDL_AcquireGPUSwapchainTexture, defined at SDL3/SDL_gpu.h 4290:34

Since: 3.2.0

Blocks the thread until a swapchain texture is available to be acquired.

Returns

true on success, false on failure; call SDL_GetError() for more information.

Thread safety

This function should only be called from the thread that created the window.

See also

sDL_AcquireGPUSwapchainTexture, sDL_WaitAndAcquireGPUSwapchainTexture, sDL_SetGPUAllowedFramesInFlight

C declaration

SDL_WaitForGPUSwapchain, defined at SDL3/SDL_gpu.h 4314:34

Since: 3.2.0

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.

Returns

true on success, false on error; call SDL_GetError() for more information.

Thread safety

This function should only be called from the thread that created the window.

See also

sDL_SubmitGPUCommandBuffer, sDL_SubmitGPUCommandBufferAndAcquireFence, sDL_AcquireGPUSwapchainTexture

C declaration

SDL_WaitAndAcquireGPUSwapchainTexture, defined at SDL3/SDL_gpu.h 4360:34

Since: 3.2.0

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.

Returns

true on success, false on failure; call SDL_GetError() for more information.

See also

sDL_AcquireGPUCommandBuffer, sDL_WaitAndAcquireGPUSwapchainTexture, sDL_AcquireGPUSwapchainTexture, sDL_SubmitGPUCommandBufferAndAcquireFence

C declaration

SDL_SubmitGPUCommandBuffer, defined at SDL3/SDL_gpu.h 4388:34

Since: 3.2.0

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.

Returns

a fence associated with the command buffer, or NULL on failure; call SDL_GetError() for more information.

See also

sDL_AcquireGPUCommandBuffer, sDL_WaitAndAcquireGPUSwapchainTexture, sDL_AcquireGPUSwapchainTexture, sDL_SubmitGPUCommandBuffer, sDL_ReleaseGPUFence

C declaration

SDL_SubmitGPUCommandBufferAndAcquireFence, defined at SDL3/SDL_gpu.h 4415:44

Since: 3.2.0

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.

Returns

true on success, false on error; call SDL_GetError() for more information.

See also

sDL_WaitAndAcquireGPUSwapchainTexture, sDL_AcquireGPUCommandBuffer, sDL_AcquireGPUSwapchainTexture

C declaration

SDL_CancelGPUCommandBuffer, defined at SDL3/SDL_gpu.h 4440:34

Since: 3.2.0

Blocks the thread until the GPU is completely idle.

Returns

true on success, false on failure; call SDL_GetError() for more information.

See also

sDL_WaitForGPUFences

C declaration

SDL_WaitForGPUIdle, defined at SDL3/SDL_gpu.h 4454:34

Since: 3.2.0

Blocks the thread until the given fences are signaled.

Returns

true on success, false on failure; call SDL_GetError() for more information.

See also

sDL_SubmitGPUCommandBufferAndAcquireFence, sDL_WaitForGPUIdle

C declaration

SDL_WaitForGPUFences, defined at SDL3/SDL_gpu.h 4473:34

Since: 3.2.0

Checks the status of a fence.

Returns

true if the fence is signaled, false if it is not.

See also

sDL_SubmitGPUCommandBufferAndAcquireFence

C declaration

SDL_QueryGPUFence, defined at SDL3/SDL_gpu.h 4490:34

Since: 3.2.0

Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence.

You must not reference the fence after calling this function.

See also

sDL_SubmitGPUCommandBufferAndAcquireFence

C declaration

SDL_ReleaseGPUFence, defined at SDL3/SDL_gpu.h 4506:34

Since: 3.2.0

Obtains the texel block size for a texture format.

Returns

the texel block size of the texture format.

See also

sDL_UploadToGPUTexture

C declaration

SDL_GPUTextureFormatTexelBlockSize, defined at SDL3/SDL_gpu.h 4522:36

Since: 3.2.0

Determines whether a texture format is supported for a given type and usage.

Returns

whether the texture format is supported for this type and usage.

C declaration

SDL_GPUTextureSupportsFormat, defined at SDL3/SDL_gpu.h 4537:34

Since: 3.2.0

Determines if a sample count for a texture format is supported.

Returns

whether the sample count is supported for this texture format.

C declaration

SDL_GPUTextureSupportsSampleCount, defined at SDL3/SDL_gpu.h 4553:34

Since: 3.2.0

Calculate the size in bytes of a texture format with dimensions.

Returns

the size of a texture with this format and dimensions.

C declaration

SDL_CalculateGPUTextureFormatSize, defined at SDL3/SDL_gpu.h 4569:36

Since: 3.2.0

Get the SDL pixel format corresponding to a GPU texture format.

Returns

the corresponding pixel format, or SDL_PIXELFORMAT_UNKNOWN if there is no corresponding pixel format.

C declaration

SDL_GetPixelFormatFromGPUTextureFormat, defined at SDL3/SDL_gpu.h 4584:45

Since: 3.4.0

Get the GPU texture format corresponding to an SDL pixel format.

Returns

the corresponding GPU texture format, or SDL_GPU_TEXTUREFORMAT_INVALID if there is no corresponding GPU texture format.

C declaration

SDL_GetGPUTextureFormatFromPixelFormat, defined at SDL3/SDL_gpu.h 4596:50

Since: 3.4.0