Catcrafts/Crafter.Graphics
Watch
2
0
Fork
You've already forked Crafter.Graphics
 0
Code Issues 25 Pull requests Projects Releases Packages Wiki Activity Actions

feat(device): applications ask for the device features their shaders use

Browse source 
Device
- Device::Initialize(required, optional) takes DeviceFeatures, the five
  core feature structs vulkan10 to vulkan14. The library enables only what
  its own shaders and code use. Device::enabledFeatures says what was
  enabled, supportedFeatures what the GPU has, apiVersion the version in
  use.
- shaderInt16, shaderFloat16, storageBuffer16BitAccess, scalarBlockLayout
  and the uniform-buffer, storage-buffer and storage-image non-uniform
  indexing bits are no longer enabled for everyone. An application whose
  shaders take uint16_t spec constants passes
  {.vulkan10 = {.shaderInt16 = VK_TRUE}}. scalarBlockLayout stays on with
  the NVIDIA workaround, whose TLAS address may sit in a struct's tail
  padding.
- Every GPU is weighed before one is chosen: Vulkan 1.3, the swapchain and,
  below 1.4, maintenance5 extensions, the library's needs, the required
  features. One that can't run the application is skipped, saying why when
  it ranks higher. A CPU device runs it only when nothing else is listed,
  and CRAFTER_GRAPHICS_DEVICE never falls back. A GPU two drivers both list
  is tried through each.
- When no GPU qualifies, Initialize throws naming each GPU's gaps. It
  destroys the instance it made, before any Wayland connection, so it can
  be called again asking for less.
- maintenance5 is vulkan14's on a 1.4 GPU and VK_KHR_maintenance5's below.
  CRAFTER_GRAPHICS_NO_VULKAN_1_4 runs as a 1.3 application, to exercise
  that path on a 1.4 GPU.
- VK_KHR_spirv_1_4 and VK_KHR_shader_float_controls, core since 1.2, are no
  longer enabled, nor VK_EXT_shader_atomic_float, which was enabled without
  its feature struct. memoryDecompression's feature bit is queried before
  it is enabled.

Shaders
- VulkanShader checks a module's capabilities, declared directly or
  implicitly, against the enabled core features, the GPU's subgroup
  operations and the optional groups, and throws naming the field to pass,
  or saying the GPU lacks it. The tables are generated from vk.xml and
  SPIR-V's grammar.
- WorkaroundNvidiaAS::Patch sized a row-major matrix push member by its
  columns, so the TLAS address could land inside it.

Window
- The swapchain format is one whose own feature flags allow storage reads
  and writes without a format, which since Vulkan 1.3 each format says for
  itself; shaderStorageImageRead/WriteWithoutFormat are no longer required.

Tests
- DeviceFeatures: ResolveFeatures, ChooseDevice and CheckShaderCapabilities,
  without a GPU.
- FeatureRequests: required and optional features end to end, the 1.3
  path, and a retry after a refusal.
- PushConstantRewrite: a row-major mat3x4 push member.
- HeapASRead, HeapDynamicIndexHit, RTPassPushData and the ray-tracing
  examples ask for the features their shaders use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jorijn van der Graaf 2026-10-31 06:40:02 +01:00
commit bcdc885de8
Signed by: jorijnvdgraaf
GPG key ID: 2937E59CDCC1BCFB
18 changed files with 1721 additions and 333 deletions
Download patch file Download diff file Expand all files Collapse all files

364
tests/DeviceFeatures/main.cpp Normal file
View file

@ -0,0 +1,364 @@
//SPDX-License-Identifier: LGPL-3.0-only
//SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
// Device::Initialize enables what the library's own shaders use plus what the
// application passes it, skips a GPU that lacks any of that, and VulkanShader
// refuses a module that declares a capability nobody enabled. The decisions
// behind those are pure logic: Device::ResolveFeatures (the features to
// enable, and the gaps a GPU has), Device::ChooseDevice (the GPU to use) and
// Device::CheckShaderCapabilities (whether a module's capabilities are
// enabled). This test drives them with synthetic GPUs and hand-built SPIR-V,
// so it needs no GPU, mirroring PipelineCacheValidation. tests/FeatureRequests
// checks the same wiring end to end on a real GPU.
#include <cstdlib>
#include <cstring>
#include <stddef.h>
#include "vulkan/vulkan.h"
import Crafter.Graphics;
import std;
using namespace Crafter;
namespace {
int failures = 0;
void Check(bool ok, std::string_view what) {
std::println("{} {}", ok ? "PASS" : "FAIL", what);
if (!ok) ++failures;
}
// The five core feature structs as DeviceFeatures lays them out: where each
// one's VkBool32 members start, and how many it has (vk.xml; a core feature
// struct never changes once its version ships).
struct Block {
std::string_view version;
std::size_t first;
std::size_t count;
};
const std::array<Block, 5> blocks {{
{ "vulkan10", offsetof(DeviceFeatures, vulkan10) + offsetof(VkPhysicalDeviceFeatures, robustBufferAccess), 55 },
{ "vulkan11", offsetof(DeviceFeatures, vulkan11) + offsetof(VkPhysicalDeviceVulkan11Features, storageBuffer16BitAccess), 12 },
{ "vulkan12", offsetof(DeviceFeatures, vulkan12) + offsetof(VkPhysicalDeviceVulkan12Features, samplerMirrorClampToEdge), 47 },
{ "vulkan13", offsetof(DeviceFeatures, vulkan13) + offsetof(VkPhysicalDeviceVulkan13Features, robustImageAccess), 15 },
{ "vulkan14", offsetof(DeviceFeatures, vulkan14) + offsetof(VkPhysicalDeviceVulkan14Features, globalPriorityQuery), 21 },
}};
void SetSlot(DeviceFeatures& features, std::size_t offset) {
const VkBool32 on = VK_TRUE;
std::memcpy(reinterpret_cast<std::byte*>(&features) + offset, &on, sizeof(on));
}
// Whether a and b have the same VkBool32s on, ignoring sType, pNext and
// padding.
bool SameFeatures(const DeviceFeatures& a, const DeviceFeatures& b) {
for (const Block& block : blocks) {
for (std::size_t i = 0; i < block.count; ++i) {
const std::size_t offset = block.first + i * sizeof(VkBool32);
VkBool32 x;
VkBool32 y;
std::memcpy(&x, reinterpret_cast<const std::byte*>(&a) + offset, sizeof(x));
std::memcpy(&y, reinterpret_cast<const std::byte*>(&b) + offset, sizeof(y));
if ((x != VK_FALSE) != (y != VK_FALSE)) {
return false;
}
}
}
return true;
}
// Every core feature on.
DeviceFeatures AllOn() {
DeviceFeatures features;
for (const Block& block : blocks) {
for (std::size_t i = 0; i < block.count; ++i) {
SetSlot(features, block.first + i * sizeof(VkBool32));
}
}
return features;
}
// A module that declares Shader and then `capabilities`, ending the
// capability section with an OpMemoryModel.
std::vector<std::uint32_t> Module(std::initializer_list<std::uint32_t> capabilities) {
constexpr std::uint32_t opCapability = 17;
constexpr std::uint32_t opMemoryModel = 14;
std::vector<std::uint32_t> words { 0x07230203u, 0x00010400u, 0, 1, 0 };
words.insert(words.end(), { opCapability | (2u << 16), 1 /* Shader */ });
for (std::uint32_t capability : capabilities) {
words.insert(words.end(), { opCapability | (2u << 16), capability });
}
words.insert(words.end(), { opMemoryModel | (3u << 16), 0, 1 });
return words;
}
// The message CheckShaderCapabilities throws for `spirv`, or "" when it lets
// the module through.
std::string Refusal(const std::vector<std::uint32_t>& spirv) {
try {
Device::CheckShaderCapabilities(spirv, "shaders/test.comp.spv");
} catch (const std::runtime_error& error) {
return error.what();
}
return "";
}
// A 1.4 GPU with every core feature, enabled nowhere, and no optional group.
void ResetDevice() {
Device::enabledFeatures = {};
Device::supportedFeatures = AllOn();
Device::apiVersion = VK_API_VERSION_1_4;
Device::vulkan11Properties = { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_PROPERTIES };
Device::vulkan11Properties.subgroupSupportedOperations = VK_SUBGROUP_FEATURE_BASIC_BIT;
Device::shaderInt64ForWorkaroundOnly = false;
Device::descriptorHeapSupported = false;
Device::rayTracingSupported = false;
}
} // namespace
int main() {
// --- what gets enabled --------------------------------------------------
{
DeviceFeatures library;
library.vulkan10.samplerAnisotropy = VK_TRUE;
// Designated initializers leave sType zero, as an application's will.
const DeviceFeatures required { .vulkan12 = { .shaderFloat16 = VK_TRUE } };
const DeviceFeatures optional {
.vulkan11 = { .storageBuffer16BitAccess = VK_TRUE },
.vulkan13 = { .synchronization2 = VK_TRUE },
};
DeviceFeatures supported = AllOn();
supported.vulkan13.synchronization2 = VK_FALSE;
FeatureGaps gaps;
const DeviceFeatures enabled = Device::ResolveFeatures(library, required, optional, supported, VK_API_VERSION_1_4, gaps);
Check(gaps.library.empty() && gaps.application.empty(), "a GPU with everything needed has no gaps");
Check(enabled.vulkan10.samplerAnisotropy && enabled.vulkan12.shaderFloat16,
"the library's and the application's required features are enabled");
Check(enabled.vulkan11.storageBuffer16BitAccess, "an optional feature the GPU has is enabled");
Check(!enabled.vulkan13.synchronization2, "an optional feature the GPU lacks stays off, silently");
Check(!enabled.vulkan10.shaderInt16 && !enabled.vulkan14.pushDescriptor,
"nothing nobody asked for is enabled");
Check(enabled.vulkan12.sType == VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES && enabled.vulkan12.pNext == nullptr,
"the result carries the sTypes and no pNext, ready to chain");
}
// --- gaps, by who needs the feature -------------------------------------
{
DeviceFeatures library;
library.vulkan10.samplerAnisotropy = VK_TRUE;
const DeviceFeatures required { .vulkan12 = { .shaderFloat16 = VK_TRUE } };
DeviceFeatures supported = AllOn();
supported.vulkan10.samplerAnisotropy = VK_FALSE;
supported.vulkan12.shaderFloat16 = VK_FALSE;
FeatureGaps gaps;
const DeviceFeatures enabled = Device::ResolveFeatures(library, required, {}, supported, VK_API_VERSION_1_4, gaps);
Check(gaps.library == std::vector<std::string>{ "vulkan10.samplerAnisotropy" },
"a library need the GPU lacks is the library's gap");
Check(gaps.application == std::vector<std::string>{ "vulkan12.shaderFloat16" },
"a required feature the GPU lacks is the application's gap, named as the application writes it");
Check(!enabled.vulkan12.shaderFloat16, "a feature the GPU lacks is never enabled");
}
// --- Vulkan 1.3 GPUs ----------------------------------------------------
{
DeviceFeatures library;
library.vulkan14.maintenance5 = VK_TRUE;
const DeviceFeatures required { .vulkan14 = { .pushDescriptor = VK_TRUE } };
// Below 1.4 a GPU supports no vulkan14 feature but maintenance5, which
// Initialize copies there from VK_KHR_maintenance5's struct (that copy
// is tests/FeatureRequests' to check, on a real GPU).
DeviceFeatures supported = AllOn();
supported.vulkan14 = { .maintenance5 = VK_TRUE };
FeatureGaps gaps;
const DeviceFeatures enabled = Device::ResolveFeatures(library, required, {}, supported, VK_API_VERSION_1_3, gaps);
Check(gaps.library.empty() && enabled.vulkan14.maintenance5,
"at 1.3 a supported vulkan14.maintenance5 meets the library's need, with no version note");
Check(gaps.application == std::vector<std::string>{ "vulkan14.pushDescriptor (Vulkan 1.4 only)" },
"at 1.3 a required vulkan14 feature is a gap that names the version");
FeatureGaps noMaintenance5;
DeviceFeatures without = AllOn();
without.vulkan14 = {};
Device::ResolveFeatures(library, {}, {}, without, VK_API_VERSION_1_3, noMaintenance5);
Check(noMaintenance5.library == std::vector<std::string>{ "vulkan14.maintenance5 (VK_KHR_maintenance5 reports it unsupported)" },
"at 1.3 a missing maintenance5 blames VK_KHR_maintenance5's feature bit, not the version");
FeatureGaps gaps14;
DeviceFeatures supported14 = AllOn();
supported14.vulkan14.pushDescriptor = VK_FALSE;
Device::ResolveFeatures(library, required, {}, supported14, VK_API_VERSION_1_4, gaps14);
Check(gaps14.application == std::vector<std::string>{ "vulkan14.pushDescriptor" },
"at 1.4 the same gap carries no version note");
}
// --- every core feature, by name ----------------------------------------
{
std::set<std::string> names;
bool eachNamedOnce = true;
bool eachEnabledAlone = true;
bool eachUnderItsVersion = true;
for (const Block& block : blocks) {
for (std::size_t i = 0; i < block.count; ++i) {
DeviceFeatures required;
SetSlot(required, block.first + i * sizeof(VkBool32));
FeatureGaps gaps;
Device::ResolveFeatures({}, required, {}, {}, VK_API_VERSION_1_4, gaps);
if (gaps.application.size() != 1 || !names.insert(gaps.application[0]).second) {
eachNamedOnce = false;
continue;
}
eachUnderItsVersion = eachUnderItsVersion && gaps.application[0].starts_with(std::format("{}.", block.version));
// On a GPU with everything, only that one gets enabled.
FeatureGaps none;
const DeviceFeatures enabled = Device::ResolveFeatures({}, required, {}, AllOn(), VK_API_VERSION_1_4, none);
eachEnabledAlone = eachEnabledAlone && SameFeatures(enabled, required);
}
}
Check(eachNamedOnce && names.size() == 150, "each of the 150 core features has a gap name of its own");
Check(eachUnderItsVersion, "each name starts with its struct's member in DeviceFeatures");
Check(eachEnabledAlone, "requiring one feature enables that one alone");
Check(names.contains("vulkan10.robustBufferAccess") && names.contains("vulkan10.shaderInt16")
&& names.contains("vulkan11.storageBuffer16BitAccess") && names.contains("vulkan12.scalarBlockLayout")
&& names.contains("vulkan14.pushDescriptor"),
"names match the members (spot checks)");
}
// --- choosing the GPU ---------------------------------------------------
{
const std::vector<std::string> noGaps;
const std::vector<std::string> gap { "lacks vulkan12.shaderFloat16, which the application requires" };
const DeviceChoice discrete { VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU, "dGPU", noGaps };
const DeviceChoice discreteLacking { VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU, "old dGPU", gap };
const DeviceChoice integrated { VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU, "iGPU", noGaps };
const DeviceChoice integratedLacking { VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU, "old iGPU", gap };
const DeviceChoice cpu { VK_PHYSICAL_DEVICE_TYPE_CPU, "llvmpipe", noGaps };
Check(Device::ChooseDevice(std::vector{ integrated, discrete }) == 1, "a discrete GPU wins over an integrated one");
Check(Device::ChooseDevice(std::vector{ discrete, discrete }) == 0, "of two equal GPUs the first is used");
Check(Device::ChooseDevice(std::vector{ discreteLacking, integrated, cpu }) == 1,
"a GPU that lacks something is skipped for the next one that can run the application");
Check(Device::ChooseDevice(std::vector{ cpu }) == 0, "a CPU device runs the application when nothing else is listed");
std::string message;
try {
Device::ChooseDevice(std::vector{ discreteLacking, integratedLacking, cpu });
} catch (const std::runtime_error& error) {
message = error.what();
}
Check(!message.empty(), "GPUs that lack something don't fall back to a CPU device");
Check(message.contains("old dGPU: lacks vulkan12.shaderFloat16") && message.contains("old iGPU: lacks")
&& message.contains("llvmpipe: a CPU device"),
"the error names every GPU and why it can't be used");
std::string none;
try {
Device::ChooseDevice(std::vector<DeviceChoice>{});
} catch (const std::runtime_error& error) {
none = error.what();
}
Check(none.contains("lists none"), "no GPU at all is an error that says so");
}
// --- SPIR-V capabilities against the enabled features -------------------
{
constexpr std::uint32_t int16 = 22;
constexpr std::uint32_t int64 = 11;
constexpr std::uint32_t int64Atomics = 12;
constexpr std::uint32_t storageImageReadWithoutFormat = 55;
constexpr std::uint32_t groupNonUniform = 61;
constexpr std::uint32_t groupNonUniformArithmetic = 63;
constexpr std::uint32_t shaderNonUniform = 5301;
constexpr std::uint32_t rayQueryKHR = 4472;
constexpr std::uint32_t descriptorHeapEXT = 5128;
constexpr std::uint32_t groupNonUniformRotateKHR = 6026;
constexpr std::uint32_t floatControls2 = 6029;
ResetDevice();
const std::string refusal = Refusal(Module({ int16 }));
Check(refusal.contains("shaders/test.comp.spv") && refusal.contains("Int16")
&& refusal.contains("vulkan10.shaderInt16: pass it to Device::Initialize"),
"Int16 without shaderInt16, on a GPU that has it, is refused, naming the file and the field to pass");
Device::enabledFeatures.vulkan10.shaderInt16 = VK_TRUE;
Check(Refusal(Module({ int16 })).empty(), "...and accepted once shaderInt16 is enabled");
ResetDevice();
Device::supportedFeatures.vulkan10.shaderInt16 = VK_FALSE;
Check(Refusal(Module({ int16 })).contains("this GPU lacks it"),
"on a GPU without shaderInt16 the refusal says the GPU lacks it, not to pass it");
ResetDevice();
Device::apiVersion = VK_API_VERSION_1_3;
Device::supportedFeatures.vulkan14 = { .maintenance5 = VK_TRUE };
Check(Refusal(Module({ floatControls2 })).contains("a Vulkan 1.4 feature, and this GPU runs Vulkan 1.3"),
"a vulkan14 capability on a 1.3 GPU names the version");
ResetDevice();
Check(Refusal(Module({ floatControls2 })).contains("vulkan14.shaderFloatControls2: pass it"),
"FloatControls2 is refused without vulkan14.shaderFloatControls2");
Device::enabledFeatures.vulkan14.shaderFloatControls2 = VK_TRUE;
Check(Refusal(Module({ floatControls2 })).empty(), "...and accepted with it");
ResetDevice();
Check(Refusal(Module({ storageImageReadWithoutFormat, shaderNonUniform })).empty(),
"capabilities a core version enables are left to the driver");
ResetDevice();
Device::enabledFeatures.vulkan10.shaderInt64 = VK_TRUE;
Device::shaderInt64ForWorkaroundOnly = true;
Check(Refusal(Module({ int64 })).contains("NVIDIA workaround"),
"Int64 on only for the NVIDIA workaround doesn't let an application's Int64 through");
Device::shaderInt64ForWorkaroundOnly = false;
Check(Refusal(Module({ int64 })).empty(), "...but does once the application asked for shaderInt64");
ResetDevice();
Device::enabledFeatures.vulkan12.shaderSharedInt64Atomics = VK_TRUE;
Check(Refusal(Module({ int64Atomics })).contains("Int64Atomics, which implicitly declares Int64"),
"Int64Atomics alone still needs shaderInt64: it implicitly declares Int64");
Device::enabledFeatures.vulkan10.shaderInt64 = VK_TRUE;
Check(Refusal(Module({ int64Atomics })).empty(), "a capability with two enabling features takes either");
Device::shaderInt64ForWorkaroundOnly = true;
Check(Refusal(Module({ int64Atomics })).contains("NVIDIA workaround"),
"an implied Int64 doesn't pass on the NVIDIA workaround's shaderInt64 either");
ResetDevice();
Check(Refusal(Module({ groupNonUniformArithmetic })).contains("VK_SUBGROUP_FEATURE_ARITHMETIC_BIT"),
"subgroup arithmetic the GPU lacks is refused");
Device::vulkan11Properties.subgroupSupportedOperations |= VK_SUBGROUP_FEATURE_ARITHMETIC_BIT;
Check(Refusal(Module({ groupNonUniformArithmetic })).empty(),
"...and accepted where the GPU has it, whatever the stage: Vulkan gates running subgroup operations by stage, not declaring them");
Device::enabledFeatures.vulkan14.shaderSubgroupRotate = VK_TRUE;
Device::vulkan11Properties.subgroupSupportedOperations = 0;
Check(Refusal(Module({ groupNonUniformRotateKHR })).contains("implicitly declares GroupNonUniform, but this GPU has no"),
"GroupNonUniformRotateKHR implicitly declares GroupNonUniform, and is held to it");
ResetDevice();
Check(Refusal(Module({ rayQueryKHR })).contains("Device::rayTracingSupported"),
"a ray-query module is refused where ray tracing is off");
Device::rayTracingSupported = true;
Check(Refusal(Module({ rayQueryKHR })).empty(), "...and accepted where it is on");
Check(Refusal(Module({ descriptorHeapEXT })).contains("Device::descriptorHeapSupported"),
"a descriptor-heap module is refused where the heap is off");
Device::descriptorHeapSupported = true;
Check(Refusal(Module({ descriptorHeapEXT })).empty(), "...and accepted where it is on");
ResetDevice();
std::vector<std::uint32_t> afterLayout = Module({});
afterLayout.insert(afterLayout.end(), { 17u | (2u << 16), int16 });
Check(Refusal(afterLayout).empty(), "only the capability section at the start of the module is read");
std::vector<std::uint32_t> malformed { 0x07230203u, 0x00010400u, 0, 1, 0, 17u /* length 0 */ };
Check(Refusal(malformed).empty(), "a malformed instruction ends the scan instead of running past the module");
Check(Refusal(Module({ groupNonUniform })).empty(), "GroupNonUniform passes on the BASIC operations every GPU has");
}
ResetDevice();
if (failures != 0) {
std::println("{} check(s) failed", failures);
return EXIT_FAILURE;
}
std::println("all checks passed");
return EXIT_SUCCESS;
}