Repository: libsdl-org/SDL
File: include/SDL3/SDL_gpu.h (C/C++)

Code before:
 *   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.
 *
 * 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.)
 *
 * \param props the properties to use.

Review comment (suggestion):
We could maybe mention that the DLL should be in a subdirectory, per the advice of [this blog post](https://devblogs.microsoft.com/directx/gettingstarted-dx12agility/):

> The DirectX team recommends that developers avoid having Agility SDK components in the same directory as their application exe, to avoid mismatching D3D12SDKLayers with the D3D12SDKVersion of D3D12Core.dll (see [Known Issues](https://devblogs.microsoft.com/directx/gettingstarted-dx12agility/#subdirissue) for more detail)

Code after:
 *   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.)