Add hint to specify Vulkan API version to use

[TheSniperFan]

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:

1. Slang's experimental compiler flags which make Slang transpile to GLSL first and then to SPIR-V, rather than compiling directly to SPIR-V.
2. 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.

[thatcosmonaut]

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

[slouken]

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...
}

[TheSniperFan]

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.

[TheSniperFan]

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.

[slouken]

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]

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

[slouken]

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]

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]

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]

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]

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

[TheSniperFan]

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]

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.