Generalize and validate optional GPU feature properties

Fixes https://github.com/libsdl-org/SDL/issues/13139
Fixes https://github.com/libsdl-org/SDL/issues/13138
This commit is contained in:
Sam Lantinga
2025-09-29 06:55:36 -07:00
parent 37410908c7
commit f61e271e11
5 changed files with 89 additions and 51 deletions

View File

@@ -230,6 +230,13 @@
* - `drawIndirectFirstInstance` * - `drawIndirectFirstInstance`
* - `sampleRateShading` * - `sampleRateShading`
* *
* You can remove some of these requirements to increase compatibility with Android devices by using these properties when creating the GPU device with SDL_CreateGPUDeviceWithProperties():
*
* - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN
* - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN
* - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN
* - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN
*
* ### D3D12 * ### D3D12
* *
* SDL driver name: "direct3d12" * SDL driver name: "direct3d12"
@@ -238,6 +245,10 @@
* (GDK). Requires a GPU that supports DirectX 12 Feature Level 11_0 and * (GDK). Requires a GPU that supports DirectX 12 Feature Level 11_0 and
* Resource Binding Tier 2 or above. * Resource Binding Tier 2 or above.
* *
* You can remove the Tier 2 resource binding requirement to support Intel Haswell and Broadwell GPUs by using this property when creating the GPU device with SDL_CreateGPUDeviceWithProperties():
*
* - SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN
*
* ### Metal * ### Metal
* *
* SDL driver name: "metal" * SDL driver name: "metal"
@@ -2242,6 +2253,22 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice(
* useful debug information on device creation, defaults to true. * useful debug information on device creation, defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to
* use, if a specific one is desired. * 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: * These are the current shader format properties:
* *
@@ -2271,25 +2298,6 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice(
* either supports Tier 2 Resource Binding or does not support D3D12 in any * either supports Tier 2 Resource Binding or does not support D3D12 in any
* capacity. Defaults to false. * capacity. Defaults to false.
* *
* With the Vulkan renderer:
*
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN`: Enable
* 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. Defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN`: Enable device
* feature depthClamp. If disabled, there is no depth clamp support and
* enable_depth_clip in SDL_GPURasterizerState must always be set to true.
* Defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN`: Enable
* device feature drawIndirectFirstInstance. If disabled, the argument
* first_instance of SDL_GPUIndirectDrawCommand must be set to zero.
* Defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN`: Enable
* device feature samplerAnisotropy. If disabled, enable_anisotropy of
* SDL_GPUSamplerCreateInfo must be set to false. Defaults to true.
*
* \param props the properties to use. * \param props the properties to use.
* \returns a GPU context on success or NULL on failure; call SDL_GetError() * \returns a GPU context on success or NULL on failure; call SDL_GetError()
* for more information. * for more information.
@@ -2308,6 +2316,10 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties(
#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" #define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower"
#define SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN "SDL.gpu.device.create.verbose" #define SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN "SDL.gpu.device.create.verbose"
#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name"
#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN "SDL.gpu.device.create.feature.clip_distance"
#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN "SDL.gpu.device.create.feature.depth_clamping"
#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN "SDL.gpu.device.create.feature.indirect_draw_first_instance"
#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN "SDL.gpu.device.create.feature.anisotropy"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" #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_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc"
@@ -2316,10 +2328,6 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties(
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" #define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib"
#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN "SDL.gpu.device.create.d3d12.allowtier1resourcebinding" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN "SDL.gpu.device.create.d3d12.allowtier1resourcebinding"
#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN "SDL.gpu.device.create.vulkan.shaderclipdistance"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN "SDL.gpu.device.create.vulkan.depthclamp"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN "SDL.gpu.device.create.vulkan.drawindirectfirstinstance"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN "SDL.gpu.device.create.vulkan.sampleranisotropy"
/** /**
* Destroys a GPU context previously returned by SDL_CreateGPUDevice. * Destroys a GPU context previously returned by SDL_CreateGPUDevice.

View File

@@ -719,6 +719,9 @@ SDL_GPUDevice *SDL_CreateGPUDeviceWithProperties(SDL_PropertiesID props)
if (result != NULL) { if (result != NULL) {
result->backend = selectedBackend->name; result->backend = selectedBackend->name;
result->debug_mode = debug_mode; result->debug_mode = debug_mode;
result->validate_feature_depth_clamp_disabled = !SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN, true);
result->validate_feature_indirect_draw_first_instance_disabled = !SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN, true);
result->validate_feature_anisotropy_disabled = !SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN, true);
} }
} }
return result; return result;
@@ -1104,6 +1107,12 @@ SDL_GPUGraphicsPipeline *SDL_CreateGPUGraphicsPipeline(
CHECK_STENCILOP_ENUM_INVALID(stencil_state->pass_op, NULL) CHECK_STENCILOP_ENUM_INVALID(stencil_state->pass_op, NULL)
CHECK_STENCILOP_ENUM_INVALID(stencil_state->depth_fail_op, NULL) CHECK_STENCILOP_ENUM_INVALID(stencil_state->depth_fail_op, NULL)
} }
if (device->validate_feature_depth_clamp_disabled &&
!graphicsPipelineCreateInfo->rasterizer_state.enable_depth_clip) {
SDL_assert_release(!"Rasterizer state enable_depth_clip must be set to true (FEATURE_DEPTH_CLAMPING disabled)");
return NULL;
}
} }
return device->CreateGraphicsPipeline( return device->CreateGraphicsPipeline(
@@ -1122,6 +1131,14 @@ SDL_GPUSampler *SDL_CreateGPUSampler(
return NULL; return NULL;
} }
if (device->debug_mode) {
if (device->validate_feature_anisotropy_disabled &&
createinfo->enable_anisotropy) {
SDL_assert_release(!"enable_anisotropy must be set to false (FEATURE_ANISOTROPY disabled)");
return NULL;
}
}
return device->CreateSampler( return device->CreateSampler(
device->driverData, device->driverData,
createinfo); createinfo);
@@ -2164,6 +2181,11 @@ void SDL_DrawGPUIndexedPrimitives(
CHECK_RENDERPASS CHECK_RENDERPASS
CHECK_GRAPHICS_PIPELINE_BOUND CHECK_GRAPHICS_PIPELINE_BOUND
SDL_GPU_CheckGraphicsBindings(render_pass); SDL_GPU_CheckGraphicsBindings(render_pass);
if (RENDERPASS_DEVICE->validate_feature_indirect_draw_first_instance_disabled &&
first_instance != 0) {
SDL_assert_release(!"first_instance must be 0 (FEATURE_INDIRECT_DRAW_FIRST_INSTANCE disabled)");
return;
}
} }
RENDERPASS_DEVICE->DrawIndexedPrimitives( RENDERPASS_DEVICE->DrawIndexedPrimitives(
@@ -2191,6 +2213,11 @@ void SDL_DrawGPUPrimitives(
CHECK_RENDERPASS CHECK_RENDERPASS
CHECK_GRAPHICS_PIPELINE_BOUND CHECK_GRAPHICS_PIPELINE_BOUND
SDL_GPU_CheckGraphicsBindings(render_pass); SDL_GPU_CheckGraphicsBindings(render_pass);
if (RENDERPASS_DEVICE->validate_feature_indirect_draw_first_instance_disabled &&
first_instance != 0) {
SDL_assert_release(!"first_instance must be 0 (FEATURE_INDIRECT_DRAW_FIRST_INSTANCE disabled)");
return;
}
} }
RENDERPASS_DEVICE->DrawPrimitives( RENDERPASS_DEVICE->DrawPrimitives(

View File

@@ -1096,6 +1096,9 @@ struct SDL_GPUDevice
// Store this for SDL_gpu.c's debug layer // Store this for SDL_gpu.c's debug layer
bool debug_mode; bool debug_mode;
bool validate_feature_depth_clamp_disabled;
bool validate_feature_indirect_draw_first_instance_disabled;
bool validate_feature_anisotropy_disabled;
}; };
#define ASSIGN_DRIVER_FUNC(func, name) \ #define ASSIGN_DRIVER_FUNC(func, name) \

View File

@@ -11739,10 +11739,10 @@ static bool VULKAN_PrepareDriver(SDL_VideoDevice *_this, SDL_PropertiesID props)
renderer = (VulkanRenderer *)SDL_calloc(1, sizeof(*renderer)); renderer = (VulkanRenderer *)SDL_calloc(1, sizeof(*renderer));
if (renderer) { if (renderer) {
// Opt out device features (higher compatibility in exchange for reduced functionality) // Opt out device features (higher compatibility in exchange for reduced functionality)
renderer->desiredDeviceFeatures.samplerAnisotropy = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.samplerAnisotropy = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
renderer->desiredDeviceFeatures.depthClamp = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.depthClamp = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
renderer->desiredDeviceFeatures.shaderClipDistance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.shaderClipDistance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
renderer->desiredDeviceFeatures.drawIndirectFirstInstance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.drawIndirectFirstInstance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
// These features have near universal support so they are always enabled // These features have near universal support so they are always enabled
renderer->desiredDeviceFeatures.independentBlend = VK_TRUE; renderer->desiredDeviceFeatures.independentBlend = VK_TRUE;
@@ -11788,10 +11788,10 @@ static SDL_GPUDevice *VULKAN_CreateDevice(bool debugMode, bool preferLowPower, S
renderer->allowedFramesInFlight = 2; renderer->allowedFramesInFlight = 2;
// Opt out device features (higher compatibility in exchange for reduced functionality) // Opt out device features (higher compatibility in exchange for reduced functionality)
renderer->desiredDeviceFeatures.samplerAnisotropy = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.samplerAnisotropy = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
renderer->desiredDeviceFeatures.depthClamp = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.depthClamp = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
renderer->desiredDeviceFeatures.shaderClipDistance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.shaderClipDistance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
renderer->desiredDeviceFeatures.drawIndirectFirstInstance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN, true) ? VK_TRUE : VK_FALSE; renderer->desiredDeviceFeatures.drawIndirectFirstInstance = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN, true) ? VK_TRUE : VK_FALSE;
// These features have near universal support so they are always enabled // These features have near universal support so they are always enabled
renderer->desiredDeviceFeatures.independentBlend = VK_TRUE; renderer->desiredDeviceFeatures.independentBlend = VK_TRUE;

View File

@@ -1313,17 +1313,17 @@ static bool GPU_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, SDL_P
SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN, true); SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN, true);
} }
// These properties allow using the renderer on more Android devices. // These properties allow using the renderer on more Android devices.
if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN)) { if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN)) {
SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN, false); SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN, false);
} }
if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN)) { if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN)) {
SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN, false); SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN, false);
} }
if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN)) { if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN)) {
SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN, false); SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN, false);
} }
if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN)) { if (!SDL_HasProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN)) {
SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN, false); SDL_SetBooleanProperty(create_props, SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN, false);
} }
GPU_FillSupportedShaderFormats(create_props); GPU_FillSupportedShaderFormats(create_props);