Allow SDL GPU to opt into additional Vulkan features #14204

TheSniperFan · 2025-10-10T15:52:47Z

Currently SDL_gpu_vulkan.c hardcodes API version 1.0 when creating the Vulkan instance for the program. This creates a problem for my use-case.

I'd like to use Slang for shader development, but SPIR-V 1.0 support is experimental. I tried two solutions and both work:

Slang's experimental compiler flags which make Slang transpile to GLSL first and then to SPIR-V, rather than compiling directly to SPIR-V.
Add a hint to SDL to allow creating instances with higher API versions.

I looked at the Vulkan documentation (specifically this and this). It says "Deprecated items will still work in current Vulkan implementations", which makes me prefer option 2. A Vulkan application requesting 1.3, but using only 1.0 features should work just fine. And using a hint doesn't change SDL's default behavior.

Since I don't know why this was hardcoded, I figured I'd first ask if there's any chance of this merge request going anywhere. Before I waste time cleaning something up that's not going to be merged for reasons I didn't know of.

This adds SDL_HINT_VULKAN_REQUEST_API_VERSION to allow requesting a specific API version when SDL creates the Vulkan instance.

src/gpu/vulkan/SDL_gpu_vulkan.c

The patch version shouldn't be relevant to the API and a new major version will likely require an entirely new renderer anyway. The benefit of this approach is that it massively simplifies parsing of the hint.

thatcosmonaut · 2025-10-10T20:38:28Z

We hardcode to 1.0 to provide maximum driver compatibility. I'm totally fine with allowing an opt-in to higher versions.

include/SDL3/SDL_hints.h

slouken · 2025-10-10T20:41:52Z

include/SDL3/SDL_hints.h

+ * This hint should be set before creating a Vulkan window. Expects a positive
+ * integer. E.g. 3 for Vulkan 1.3.


I think it's reasonable to allow specifying the full version and will be more intuitive for users. This is easily implemented with, e.g.

if (SDL_sscanf(hint, "%d.%d", &major, &minor) == 2) { ... } else { // Parse error... }

Co-authored-by: Sam Lantinga <[email protected]>

This reverts commit 6c4d2c0.

TheSniperFan · 2025-10-10T23:06:20Z

This needs a bit more time in the oven, I think.
Setting the API version during instance creation does allow Slang-compiled shaders to be loaded without the validation layer complaining. However, Slang might emit SPIR-V that relies on physical device features that would have to be specified during device creation.
I'll see if there's a sane, non-intrusive way to implement that tomorrow.

include/SDL3/SDL_hints.h

Introduces a new property to use when creating a Vulkan renderer. SDL_PROP_GPU_DEVICE_CREATE_VULKAN_ADDITIONAL_FEATURES_POINTER

Since the developer can now pass additional features to be activated, this name makes more obvious that these get enabled by SDL regardless.

TheSniperFan · 2025-10-11T15:16:09Z

I added a workflow to opt-into Vulkan device features using properties. I made sure the default behavior is unaffected. The usage code in my application look like this:

props := sdl.CreateProperties()
sdl.SetBooleanProperty(props, sdl.PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN, true)
sdl.SetBooleanProperty(props, sdl.PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN, true)
sdl.SetStringProperty(props, sdl.PROP_GPU_DEVICE_CREATE_NAME_STRING, "vulkan")

// Enable Vulkan 1.1 feature
vulkan_11_features := vk.PhysicalDeviceVulkan11Features {
	sType                = vk.StructureType.PHYSICAL_DEVICE_VULKAN_1_1_FEATURES,
	shaderDrawParameters = true,
}
sdl.SetPointerProperty(props, sdl.PROP_GPU_DEVICE_CREATE_VULKAN_ADDITIONAL_FEATURES_POINTER, rawptr(&vulkan_11_features))

result.gpu = sdl.CreateGPUDeviceWithProperties(props)

EDIT: This still needs to handle errors from unsupported features.

KHR_portability_subset structure was being overwritten by opt-in features.

slouken · 2025-10-11T16:00:36Z

I added a workflow to opt-into Vulkan device features using properties. I made sure the default behavior is unaffected. The usage code in my application look like this:

props := sdl.CreateProperties()
sdl.SetBooleanProperty(props, sdl.PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN, true)
sdl.SetBooleanProperty(props, sdl.PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN, true)
sdl.SetStringProperty(props, sdl.PROP_GPU_DEVICE_CREATE_NAME_STRING, "vulkan")

// Enable Vulkan 1.1 feature
vulkan_11_features := vk.PhysicalDeviceVulkan11Features {
	sType                = vk.StructureType.PHYSICAL_DEVICE_VULKAN_1_1_FEATURES,
	shaderDrawParameters = true,
}
sdl.SetPointerProperty(props, sdl.PROP_GPU_DEVICE_CREATE_VULKAN_ADDITIONAL_FEATURES_POINTER, rawptr(&vulkan_11_features))

result.gpu = sdl.CreateGPUDeviceWithProperties(props)

EDIT: This still needs to handle errors from unsupported features.

This seems like a reasonable workflow to me. @thatcosmonaut, thoughts?

thatcosmonaut · 2025-10-11T16:55:56Z

Yeah that does seem reasonable. Is this stable if we have to add fields to the struct?

slouken · 2025-10-11T17:00:21Z

If increasing the Vulkan version often means chaining additional device creation structures, maybe the Vulkan version should also be a property instead of a hint?

TheSniperFan · 2025-10-11T17:10:15Z

Yeah that does seem reasonable. Is this stable if we have to add fields to the struct?

I'm not sure I understand.

If increasing the Vulkan version often means chaining additional device creation structures, maybe the Vulkan version should also be a property instead of a hint?

I was thinking about the same thing. Right now, I'm looking into error handling. As it stands, the vkCreateDevice() call crashes when unsupported features are requested.

thatcosmonaut · 2025-10-11T17:40:59Z

Yeah that does seem reasonable. Is this stable if we have to add fields to the struct?

I'm not sure I understand.

We guarantee ABI stability in SDL, so if we add something we can't make future code changes that will cause an executable to break if a client updates the SDL3 DLL for example.

slouken · 2025-10-11T17:50:49Z

Yeah that does seem reasonable. Is this stable if we have to add fields to the struct?

I'm not sure I understand.

We guarantee ABI stability in SDL, so if we add something we can't make future code changes that will cause an executable to break if a client updates the SDL3 DLL for example.

Yes, this change doesn't affect any public structures, so this is ABI safe.

thatcosmonaut · 2025-10-11T18:12:58Z

Oh I just realized it's literally a pointer to the Vulkan struct, that makes sense.

TheSniperFan · 2025-10-11T18:38:37Z

If increasing the Vulkan version often means chaining additional device creation structures, maybe the Vulkan version should also be a property instead of a hint?

My current solution looks like this:

// SDL_gpu.h

#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER    "SDL.gpu.device.create.vulkan.options"

/**
 * A structure specifying additional options when using Vulkan.
 *
 * When no such structure is provided, SDL will use Vulkan API version 1.0 and a minimal set of features.
 *
 * \since This struct is available since SDL 3.4.0.
 *
 */
typedef struct SDL_GPUVulkanOptions
{
    Uint32 vulkan_api_version; /**< The Vulkan API version to request for the instance.  */
    void *physical_device_features_1_0; /**< Pointer to a VkPhysicalDeviceFeatures struct. */
    void *physical_device_features_1_1; /**< Pointer to a VkPhysicalDeviceVulkan11Features struct. */
    void *physical_device_features_1_2; /**< Pointer to a VkPhysicalDeviceVulkan12Features struct. */
    void *physical_device_features_1_3; /**< Pointer to a VkPhysicalDeviceVulkan13Features struct. */
} SDL_GPUVulkanOptions;

Providing the various structs separately rather than in a chain makes validation and error-reporting much easier.

Does this look like a workable solution?

slouken · 2025-10-12T03:46:31Z

I would prefer your original implementation which just added a single chained structure to the options. It's more flexible, and once you're using properties, you're generally speaking outside the normal development path and responsible for doing so safely.

TheSniperFan · 2025-10-12T10:33:16Z

I would prefer your original implementation which just added a single chained structure to the options. It's more flexible, and once you're using properties, you're generally speaking outside the normal development path and responsible for doing so safely.

Yeah, I started reworking it almost immediately after I posted that yesterday. It occurred to me that this structure wasn't very forward compatible.

Also replaces the previously created hint

TheSniperFan · 2025-10-12T18:07:19Z

It's worth noting that VkPhysicalDeviceVulkan11Features was actually added in Vulkan 1.2 (!) and the only way to enable Vulkan 1.1 features with a Vulkan 1.1 instance is to chain feature-specific structs like VkPhysicalDeviceShaderDrawParameterFeatures.

In that case, I think it would be better to remove the whitelist and allow passing arbitrary struct chains into device creation. As @slouken said, when you're using properties, you're responsible for using them correctly.

slouken · 2025-10-12T18:19:46Z

It's worth noting that VkPhysicalDeviceVulkan11Features was actually added in Vulkan 1.2 (!) and the only way to enable Vulkan 1.1 features with a Vulkan 1.1 instance is to chain feature-specific structs like VkPhysicalDeviceShaderDrawParameterFeatures.

In that case, I think it would be better to remove the whitelist and allow passing arbitrary struct chains into device creation. As @slouken said, when you're using properties, you're responsible for using them correctly.

Agreed.

TheSniperFan · 2025-10-12T18:43:44Z

Looking a bit deeper into the specs, it looks like Vulkan 1.1 is an annoying special case. At that point, they still haven't quite figured out how they want to handle future version extensions yet. My current implementation works with 1.2+.

Saying that using props means you're responsible for using them correctly is fine, but I'd still like SDL to do some sanity checking. At least enough to where it can fail gracefully and report useful error messages rather than just crashing.

TheSniperFan · 2025-10-12T22:34:53Z

Next draft. (Still WIP.)

/**
 * A structure specifying additional options when using Vulkan.
 *
 * When no such structure is provided, SDL will use Vulkan API version 1.0 and a minimal set of features.
 * The feature list gets passed to the vkCreateInstance function and allows requesting additional
 * features.
 * 
 * \since This struct is available since SDL 3.4.0.
 *
 */
typedef struct SDL_GPUVulkanOptions
{
    Uint32 vulkan_api_version; /**< The Vulkan API version to request for the instance. Use Vulkan's VK_MAKE_VERSION or VK_MAKE_API_VERSION. */
    void *feature_list; /**< Pointer to the first element of a list of structs to be passed to device creation. */
	void *vulkan_10_physical_device_features; /**< Pointer to a VkPhysicalDeviceFeatures struct to enable additional Vulkan 1.0 features. */
} SDL_GPUVulkanOptions;

Vulkan 1.0 features need to be passed separately, because the struct can't be chained. (This is one of the oversights I alluded to earlier.)
I implemented 3 code paths based on the api version that is passed.
Vulkan 1.0 only checks the provided 1.0 device features pointer.
Vulkan 1.1 additionally iterates over the list, collecting only the Vulkan 1.1 feature options. Thanks for bringing this to my attention, @rabbit-ecl
Vulkan 1.2+ additionally checks the VkPhysicalDeviceVulkanXXFeatures structs

E.g. Vulkan 1.3 features will be ignored if API version 1.2 or lower is requested.

flibitijibibo · 2025-10-14T15:51:33Z

This may have been answered already so apologies in advance, but is the slang compiler capable of using SPV extensions to meet 1.0 compatibility? It might be easier for us to make a property to add a list of VK extensions that allow newer features without needing to bump the whole runtime version.

TheSniperFan · 2025-10-14T20:03:32Z

This may have been answered already so apologies in advance, but is the slang compiler capable of using SPV extensions to meet 1.0 compatibility? It might be easier for us to make a property to add a list of VK extensions that allow newer features without needing to bump the whole runtime version.

I am working on something like that. This pull request started off as a version selector, but morphed into something more flexible. If you're interested in specific features, please post them here. I'll see if they can be made to fit. @flibitijibibo

Separate code-paths for 1.0, 1.1 and 1.2+

TheSniperFan · 2025-10-18T00:32:25Z

API version and device features seem to work fine now. I don't see a reason to leave extensions out. I'm extending the API to allow you to opt into those, too.

-Remove obsolete property -Clean up API version checks

TheSniperFan · 2025-10-18T13:21:31Z

Opt-in instance extensions are implemented now. I also noticed and fixed another bug while I was at it. Force-pushed to split it into a separate pull request. #14272

TheSniperFan · 2025-10-18T14:42:47Z

This pull request looks like its pretty much ready.
It got way more complex than the initial hint, but this property should expose everything that you might need. If I missed something, please let me know.

// SDL_gpu.h

typedef struct SDL_GPUVulkanOptions
{
    Uint32 vulkan_api_version; /**< The Vulkan API version to request for the instance. Use Vulkan's VK_MAKE_VERSION or VK_MAKE_API_VERSION. */
    void *feature_list; /**< Pointer to the first element of a list of structs to be passed to device creation. */
	void *vulkan_10_physical_device_features; /**< Pointer to a VkPhysicalDeviceFeatures struct to enable additional Vulkan 1.0 features. */
	Uint32 device_extension_count; /**< Number of additional device extensions to require. */
	const char **device_extension_names; /**< Pointer to a list of additional device extensions to require. */
	Uint32 instance_extension_count; /**< Number of additional instance extensions to require. */
	const char **instance_extension_names; /**< Pointer to a list of additional instance extensions to require. */
} SDL_GPUVulkanOptions;

I made sure the device features get handled in separate code-paths depending on whether you request API version 1.0, 1.1 or 1.2+. I also went out of my way to add useful error logging. It'll report the name of the feature or extension that is unsupported.

Does this look okay? @slouken @thatcosmonaut

include/SDL3/SDL_gpu.h

src/gpu/vulkan/SDL_gpu_vulkan.c

slouken · 2025-10-18T16:08:16Z

I will defer to @thatcosmonaut, but if he likes this patch, it can go in.

Error checking no longer happens in VULKAN_INTERNAL_AddOptInVulkanOptions()

Since the user might pass a pointer to the stack, we better clear this after we're done with it.

Co-authored-by: Sam Lantinga <[email protected]>

flibitijibibo

Will also defer to @thatcosmonaut here, but it does raise the question of how much stuff we could take out of the VulkanRenderer struct since a large percentage, with or without these changes, is only needed at init time. For now we can probably leave it alone, but we should check this out afterward.

flibitijibibo · 2025-10-21T14:44:42Z

src/gpu/vulkan/SDL_gpu_vulkan.c

+                }
+            }
+
+            renderer->additionalDeviceExtensionCount = options->device_extension_count;


Should we specify in the header that these pointers aren't deep-copied?

flibitijibibo · 2025-10-21T14:46:27Z

src/gpu/vulkan/SDL_gpu_vulkan.c

    }

+    // Make sure we don't hold onto potentially unsafe pointers after initialization
+    renderer->additionalDeviceExtensionCount = 0;


I wonder if it's worth making these local variables somehow, so that the VulkanRenderer doesn't have to carry this all throughout runtime.

Add hint to specify Vulkan API version to use

32a4fe2

This adds SDL_HINT_VULKAN_REQUEST_API_VERSION to allow requesting a specific API version when SDL creates the Vulkan instance.

madebr reviewed Oct 10, 2025

View reviewed changes

src/gpu/vulkan/SDL_gpu_vulkan.c Outdated Show resolved Hide resolved

Fix incorrect use of strings

c0ea6bf

madebr reviewed Oct 10, 2025

View reviewed changes

src/gpu/vulkan/SDL_gpu_vulkan.c Outdated Show resolved Hide resolved

Change hint to only specify minor version

6c4d2c0

The patch version shouldn't be relevant to the API and a new major version will likely require an entirely new renderer anyway. The benefit of this approach is that it massively simplifies parsing of the hint.

slouken added this to the 3.4.0 milestone Oct 10, 2025

slouken reviewed Oct 10, 2025

View reviewed changes

include/SDL3/SDL_hints.h Outdated Show resolved Hide resolved

slouken reviewed Oct 10, 2025

View reviewed changes

TheSniperFan and others added 3 commits October 10, 2025 23:08

Update include/SDL3/SDL_hints.h

90926f7

Co-authored-by: Sam Lantinga <[email protected]>

Revert "Change hint to only specify minor version"

db9532a

This reverts commit 6c4d2c0.

Handle errors when parsing hint

4b66c16

slouken reviewed Oct 10, 2025

View reviewed changes

include/SDL3/SDL_hints.h Outdated Show resolved Hide resolved

TheSniperFan added 3 commits October 11, 2025 14:23

Use standard version string format

1721814

Allow requesting additional Vulkan device features

0310602

Introduces a new property to use when creating a Vulkan renderer. SDL_PROP_GPU_DEVICE_CREATE_VULKAN_ADDITIONAL_FEATURES_POINTER

Rename VulkanRenderer.desiredDeviceFeatures

0bddc9c

Since the developer can now pass additional features to be activated, this name makes more obvious that these get enabled by SDL regardless.

Handle multiple chaining of structures

962026f

KHR_portability_subset structure was being overwritten by opt-in features.

Add Vulkan options property

9cd9bbd

Also replaces the previously created hint

Handle Vulkan 1.1 features properly

9dac2f6

Gate Vulkan feature requests by API version

b938d6e

E.g. Vulkan 1.3 features will be ignored if API version 1.2 or lower is requested.

TheSniperFan changed the title ~~Add hint to specify Vulkan API version to use~~ Allow opting into Vulkan features Oct 12, 2025

TheSniperFan changed the title ~~Allow opting into Vulkan features~~ Allow SDL GPU to opt into additional Vulkan features Oct 12, 2025

Fix CI errors

872aa0a

Validate requested extensions

a269ffb

Separate code-paths for 1.0, 1.1 and 1.2+

TheSniperFan added 2 commits October 18, 2025 13:44

Cleanup

bada266

-Remove obsolete property -Clean up API version checks

Implement opt-in instance extensions

cff7d01

TheSniperFan force-pushed the main branch from 9a13f3f to cff7d01 Compare October 18, 2025 13:19

TheSniperFan added 3 commits October 18, 2025 16:26

Implement opt-in device extensions

b00b4df

Add missing const

4cbb2a0

Update comment

9e26c5a

TheSniperFan marked this pull request as ready for review October 18, 2025 14:42

Fix compile error

e357936

slouken reviewed Oct 18, 2025

View reviewed changes

include/SDL3/SDL_gpu.h Outdated Show resolved Hide resolved

slouken reviewed Oct 18, 2025

View reviewed changes

src/gpu/vulkan/SDL_gpu_vulkan.c Outdated Show resolved Hide resolved

TheSniperFan and others added 3 commits October 18, 2025 18:54

Remove obsolete error check

d95f1d8

Error checking no longer happens in VULKAN_INTERNAL_AddOptInVulkanOptions()

Clear extension name pointers after initialization

a198c8c

Since the user might pass a pointer to the stack, we better clear this after we're done with it.

Update include/SDL3/SDL_gpu.h

24749c4

Co-authored-by: Sam Lantinga <[email protected]>

flibitijibibo reviewed Oct 21, 2025

View reviewed changes

		* This hint should be set before creating a Vulkan window. Expects a positive
		* integer. E.g. 3 for Vulkan 1.3.

Allow SDL GPU to opt into additional Vulkan features #14204

Are you sure you want to change the base?

Allow SDL GPU to opt into additional Vulkan features #14204

Conversation

TheSniperFan commented Oct 10, 2025

Uh oh!

Uh oh!

Uh oh!

thatcosmonaut commented Oct 10, 2025

Uh oh!

Uh oh!

slouken Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

TheSniperFan commented Oct 10, 2025

Uh oh!

Uh oh!

TheSniperFan commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slouken commented Oct 11, 2025

Uh oh!

thatcosmonaut commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slouken commented Oct 11, 2025

Uh oh!

TheSniperFan commented Oct 11, 2025

Uh oh!

thatcosmonaut commented Oct 11, 2025

Uh oh!

slouken commented Oct 11, 2025

Uh oh!

thatcosmonaut commented Oct 11, 2025

Uh oh!

TheSniperFan commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slouken commented Oct 12, 2025

Uh oh!

TheSniperFan commented Oct 12, 2025

Uh oh!

TheSniperFan commented Oct 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slouken commented Oct 12, 2025

Uh oh!

TheSniperFan commented Oct 12, 2025

Uh oh!

TheSniperFan commented Oct 12, 2025

Uh oh!

flibitijibibo commented Oct 14, 2025

Uh oh!

TheSniperFan commented Oct 14, 2025

Uh oh!

TheSniperFan commented Oct 18, 2025

Uh oh!

TheSniperFan commented Oct 18, 2025

Uh oh!

TheSniperFan commented Oct 18, 2025

Uh oh!

Uh oh!

Uh oh!

slouken commented Oct 18, 2025

Uh oh!

flibitijibibo left a comment

Choose a reason for hiding this comment

Uh oh!

flibitijibibo Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

flibitijibibo Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

TheSniperFan commented Oct 11, 2025 •

edited

Loading

thatcosmonaut commented Oct 11, 2025 •

edited

Loading

TheSniperFan commented Oct 11, 2025 •

edited

Loading

TheSniperFan commented Oct 12, 2025 •

edited

Loading