SDL_CreateGP...ithProperties(3)

✨ SDL_CreateGPUDeviceWithProperties ✨

okay bestie, welcome to the SDL3 FUNCTIONS manual, and buckle up because this one is a chonky girl. we're talking about SDL_CreateGPUDeviceWithProperties today, and she is giving main character energy, no cap 💅

---

🌸 NAME 🌸

SDL_CreateGPUDeviceWithProperties — Creates a GPU context. periodt.

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_gpu.h>

SDL_GPUDevice * SDL_CreateGPUDeviceWithProperties(
    SDL_PropertiesID props);

---

💖 DESCRIPTION 💖

so like, you hand her a bag of properties and she builds you a whole GPU context out of it. these are the supported properties, and yes, we're listing all of them, because we don't skip. skipping is not the vibe. 🫶

• SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN — turns on debug mode properties and validations. defaults to true, because she's careful like that.
• SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN — enable this if you want energy efficiency over maximum GPU performance. defaults to false, so by default she's going full throttle 🔥
• SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN — enable to automatically log useful debug information when the device gets created. defaults to true.
• SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING — the name of the GPU driver to use, if you want a specific one. picky picky, we love that for you 💅
• SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN — enables the Vulkan device feature shaderClipDistance. if you disable it, clip distances are literally not supported in shader code: that's the gl_ClipDistance[] built-ins of GLSL, the SV_ClipDistance0/1 semantics of HLSL, and the [[clip_distance]] attribute of Metal. turning off optional features lets your app run on some older Android devices. defaults to true.
• SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN — enables the 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. turning off optional features lets your app run on some older Android devices. defaults to true.
• SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN — enables the Vulkan device feature drawIndirectFirstInstance. if disabled, the argument first_instance of SDL_GPUIndirectDrawCommand must be set to zero. turning off optional features lets your app run on some older Android devices. defaults to true.
• SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN — enables the Vulkan device feature samplerAnisotropy. if disabled, enable_anisotropy of SDL_GPUSamplerCreateInfo must be set to false. turning off optional features lets your app run on some older Android devices. defaults to true.

and now, the current shader format properties 🎀 (these are giving "what shaders can you actually feed me"):

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

🚨 bestie LISTEN. be sure not to put the DLL in the same directory as the exe; Microsoft strongly advises against this! do not do it. I'm not kidding. 💀

---

🧚 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. fancy ✨

---

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

---

🍓 FUNCTION PARAMETERS 🍓

• props — the properties to use.

---

👑 RETURN VALUE 👑

returns a GPU context on success or NULL on failure; call SDL_GetError() for more information. if it's NULL, go read your error, she left you a note 💌

---

💜 AVAILABILITY 💜

this function is available since SDL 3.2.0.

---

🌸 SEE ALSO 🌸

• SDL_GetGPUShaderFormats(3)
• SDL_GetGPUDeviceDriver(3)
• SDL_DestroyGPUDevice(3)
• SDL_GPUSupportsProperties(3)

---

and that's the whole page, bestie 🫶 go forth and create your GPU context. this was brought to you by Simple Directmedia Layer, version SDL 3.4.18, and honestly? iconic. slay. bye 💅✨