ClanLib Vulkan Display Target

[rombust]

I have created a "proof of concept" Vulkan display target for ClanLib.

It was created using Sonnet 4.6 .

Is anyone interesting in helping, checking the code etc. ?

This is required to support devices that support Vulkan 1.3 and OpenGL ES 3.1

Although we used to support various OpenGL version. We don't have enough developers to ensure it's working as intended for the different versions.

[dpjudas]

How far working is it? Does it run any of the examples successfully? Do you get any device lost errors? Does it pass the vulkan validation layer on the examples?

I'm not particular interested in debugging AI generated code myself. I find this way of developing software to be basically removing the fun part and leaving me with nothing but unfun debugging bugs I didn't create myself and doing code reviews trying to minimize that.

That said, I do have extensive experience with the Vulkan API so if there are any questions or there's some issue that are puzzling you I'll gladly answer questions.

[rombust]

I have committed the Vulkan display target prototype for Windows. The X11 version might work, but I haven't updated the automake scripts at this stage to test it.

VulkanShaderObjectProvider includes glslang to convert from glsl to spirv .
I am thinking this it is preferable to only support spirv inside the actual SDK, and instead the application performs the conversion (if required). The SDK build process compiles the glsl into Spirv and includes it directly in the library (this is how D3D/Shaders/*.h works)

Debugging AI code is a pain. I have been using AI on other projects. Good for repetitive refactoring work on legacy code, but it didn't fill me with confidence when it changed random unrelated code. Double checking AI code is time consuming.

I have got Basic2D to display something. The individual components within the example appear to work (excluding some upside down issues). However when all the graphic components are enabled, I get this:

The Canvas example works, except an upside down bug when creating the holes using the mouse.

To compile Basic2D . Use x64 with Multithreaded Debug DLL, and modify the code as below:

#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/vulkan-1.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/glslangd.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/glslang-default-resource-limitsd.lib")

#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/SPIRV-Tools-diffd.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/SPIRV-Tools-linkd.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/SPIRV-Tools-lintd.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/SPIRV-Tools-optd.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/SPIRV-Toolsd.lib")
#pragma comment(lib, "C:/VulkanSDK/1.4.321.1/Lib/SPIRVd.lib")

clan::ApplicationInstance<Basic2D> clanapp;

Basic2D::Basic2D()
{
	//#if defined(WIN32) && !defined(__MINGW32__)
	//	clan::D3DTarget::set_current();
	//#else
	//	clan::OpenGLTarget::set_current();
	//#endif
	clan::VulkanContextDescription vk_desc;
	clan::VulkanTarget::enable(vk_desc);

Note. I use Visual Studio 2026 Pro. The ClanLib Wizard hasn't yet been updated to support it yet. Thus project re-targeting is required until I get around to fixing it (Plus removing android OpenGL experimental support - Even my ancient Google Pixel 5 apparently supports Vulkan 1.1 )

[dpjudas]

I'm fascinated that it got it to actually render something without crashing, but the code it produced is both amazing and horrible at the same time.

On the plus side: it created the Vulkan API calls for creating all the basic object types. It created the swap chain, command buffers and a strategy to create vulkan pipelines and descriptor sets based on the ClanLib GPU object types. There's lots of code in there one could grab and save the trouble of typing yourself.

The bad things:

1. It seems to be doing platform agnostic stuff in platform specific classes (the X11 classes created vulkan structures that isn't X11 specific - Win32 part probably does too).

2. It doesn't check the result codes for all the vulkan API calls. For instance, it calls vkCreateImageView but doesn't check if it fails. This can cause bugs later on that can become very difficult to track down.

3. It doesn't use vk_mem_alloc to manage memory allocations, instead naively calling vkAllocateMemory. This may work fine in a simple test program, but you can only make a limited amount of calls like that with Vulkan before it fails the allocation. Think of vkAllocateMemory as the equivalent of calling VirtualAlloc in the Win32 API. It allocates pages of memory, intended to be used by a memory allocator like malloc. The Vulkan equivalent of malloc is the vk_mem_alloc library. It is fairly easy to fix, but its a problem.

4. It seemingly has no strategy on what to do if a texture/buffer is updated after creation after already being in use in the current frame. It essentially has to submit the commands and wait for completion before its safe to lock/upload a texture/buffer - or alternatively create another buffer so the first one can be used by the GPU while the CPU modifies the memory.

5. I saw Vulkan specific code in an input event handler!?

6. I didn't spot any code booting the vulkan validation layer. Vulkan is notorious for not crashing on Nvidia hardware while technically being invalid API usage. Did you try run it on an AMD card? I think a developer can force the validation layer on via the Vulkan SDK on a global scale, but IMHO that's a sucky solution and also doesn't work if you have crashes on hardware you don't own yourself.

7. I didn't spot any image transition barriers. Maybe its there and I missed it - not sure. On nvidia the driver doesn't care much, but on AMD hardware that creates rendering artifacts.

8. It doesn't use volk for bindings. It just links against the vulkan library files and same for glslang. While that works the catch is that you can't dynamically adopt to the vulkan version actually available (same problem when you link directly against OpenGL). For glslang the catch is that you now have to bundle a DLL with the application.

About the ClanLib Wizard, I have written my own build tool called cppbuild that is heavily inspired by CMake. I would personally probably port ClanLib over to that than update the old wizard. Or, alternatively, add a CMakeLists.txt file if you want other people not to complain that its being "not what everyone else uses". I don't know if cppbuild is feature complete enough to do everything the old wizard was doing yet though.

[rombust]

Thank you. I will have a look at these issues.

Yes, VulkanWindowProvider_X11::on_clicked(XButtonEvent &event) contains Vulkan specific code .... interesting !!!!!!

[rombust]

That's it for today. I will have another look next week.

Implemented using "Sonnet 4.6" items: 1,2,3 and 8. Did 5 manually. Therefore, the code quality is in an unknown state.

The Basic2D example, and Canvas example both look the same as the did above (same errors, but that's expected). ("vulkan-1.lib" is not required since using volk)

[dpjudas]

I don't want to discourage you if you're having fun with this, but to be perfectly honest I'm getting a bit worried about this experimental work on the master branch. It really should be on a work branch until its stable enough to be considered a backend target on pair with the other ones.

I took a look at the follow up commits pushed and they both got seemingly nonsense included in them as well. File mode changes in both commits (github's bad UI didn't really help me see exactly what it was and what it changed it to). White-space added or removed at seemingly random locations. Functions moved to the header files without reason.

I'll be a bit honest with you. I'm one of the types that greatly dislike AI tooling. The reason is that when I look at those commits I have basically no idea if item 1, 2, 3 and 8 was actually addressed properly and in the right way. The amount of time I have to spend trying to figure that out while getting thrown curve balls like file mode and white-space changes in the middle of it is simply too mentally draining on me.

I know you didn't explicitly state that its resolved now, but that's sort of the point. When we used to develop on ClanLib together I had a fair idea of the quality of your work as I got to know you and knew what you'd commit and what you wouldn't commit. How far you tested something before committing it. And so on. With AI doing so much of the work that's all up in the air.

I could ask why the commit is using volk in this particular configuration it chose (it differs from what ZVulkan chose to do), but we both know none of us can answer that question. Is it better than what ZVulkan went for? Is it worse? Nobody knows! And that's why I don't like or trust AI. If nobody can explain the system then how can we know it works?

In any case, I'd be much more comfortable with this project if its done on a work branch and not merged into the master branch until at a minimum the vulkan validation layer produces no errors or warnings on GPU hardware from both NVIDIA and AMD. And with a developer that looked at the final code and signed off that this now looks sane and how it should look like. Basically, if I'd reject those commits as a PR sent by a human, they should also be rejected if it came from a tool.

[rombust]

You are absolutely correct. It should NOT be an the master branch, until proved stable.

I have reverted the commits.

The whitespace stuff is something I detest with AI. Looking at the commits, it's a mess.

The intention was to create a template to work with. With hindsight, that will not help anyone. The fixing the AI stuff will be a lot of noise that shouldn't be in the master branch.

[rombust]

I am looking at the upside down issue. I want to ensure I get it exactly correct, instead of flipping values and hoping for the best

In Canvas_Impl::calculate_map_mode_matrices() https://github.com/sphair/ClanLib/blob/master/Sources/Display/2D/canvas_impl.cpp

This line:
MapMode mode = (canvas_y_axis == TextureImageYAxis::y_bottom_up) ? get_top_down_map_mode() : canvas_map_mode;

Can anyone remember the logic to it ? To me, it reads like a hack.

This is my current work in progress. Basic2D and the SVG example using Vulkan:

Thanks for the suggestion of enabling validation at this stage of development. It made finding bugs much easier.

(edit) Note, the FPS is low because that's running in debug mode

[dpjudas]

The TextureImageYAxis has to do with OpenGL using an image coordinate system that is upside down.

In Direct3D 9, 11, 12 and Vulkan the frame buffer image has 0,0 as the upper left corner of the viewport. OpenGL uses lower left corner.

This means when you render to texture, for OpenGL, the image becomes "upside down" compared to how all other textures typically are arranged. For all the other graphics APIs this is not a concern. The enum is trying to support both situations - probably by asking the provider backend which one is active for this backend.

[dpjudas]

By the way - you may want to launch the test program from RenderDoc. If you do that, you can see the texture images. You want it so any render to texture in the vulkan backend does not appear upside down when viewed from RenderDoc.

My work on GZDoom I didn't do that for compatibility reasons and its so annoying to look at. May OpenGL and its lower left convention die in a fire! Amazing it took all the way until Vulkan for them to finally address this. :)

[rombust]

I have completed a working Windows version of the Vulkan Display Target, capable of running our standard examples.
See: https://github.com/rombust/ClanLib
Please can interested parties comment on it.
It should have correct whitespace this time. It was my mistake all Vulkan source whitespace appeared randomised (my brain was not engaged)

Note:
Only Windows is currently working. The X11 target is not tested. I have only tested it using a NVIDIA GPU on Windows.
The next stage will be testing using Intel GPU, and Linux X11 target. I don't have access to AMD GPU
In addition I haven't yet tested it with all my personal ClanLib projects.
I will not include it into ClanLib-master until everyone is satisfied.

Info:
The GLSL to Spv library dependency has been removed.
The GLSL shaders are located in ClanLib\Resources\VulkanShaders and compiled to ClanLib\Sources\VK\Shaders
(This is how the D3D display target does it)

Known Issues:
When testing on an old NVIDIA GPU (Quadro K4000), I get the following validation log. This is because we have 16 uniforms in our sprite shader. https://docs.vulkan.org/spec/latest/chapters/limits.html states the minimum maxPerStageDescriptorUniformBuffers supported is 12.

Tue Mar 24 10:33:40 2026 UTC [Vulkan] vkCreatePipelineLayout(): max per-stage uniform buffer bindings count (16) exceeds device maxPerStageDescriptorUniformBuffers limit (15).
The Vulkan spec states: The total number of descriptors in descriptor set layouts created without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set with a descriptorType of VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any given shader stage across all elements of pSetLayouts must be less than or equal to VkPhysicalDeviceLimits::maxPerStageDescriptorUniformBuffers (https://docs.vulkan.org/spec/latest/chapters/descriptorsets.html#VUID-VkPipelineLayoutCreateInfo-descriptorType-03017)

Examples:
These images are from the ClanLib examples with only these modifications. 64 bit build is required when the Vulkan validation layer is enabled.

(In precomp.h)

#include <ClanLib/vk.h>

(In setting the display target)

	clan::log_event("Testing", "Logging");
	clan::VulkanContextDescription vk_desc;
	vk_desc.set_debug(true);
	clan::VulkanTarget::enable(vk_desc);

(In application header)

	clan::ConsoleLogger logger;

[dpjudas]

When testing on an old NVIDIA GPU (Quadro K4000), I get the following validation log. This is because we have 16 uniforms in our sprite shader. https://docs.vulkan.org/spec/latest/chapters/limits.html states the minimum maxPerStageDescriptorUniformBuffers supported is 12.

I'm not sure I fully understand this. Is the current implementation creating a completely new uniform buffer for each uniform? If so, that is not a very good idea.

What it should do is create a single uniform buffer for all the uniforms not placed in a buffer on their own. If one of the uniforms is modified it needs to stream in a new version of the buffer for the shader. Or you could stream them in via push constants.

The push constants is a special type of uniform that can be modified in the command buffer using vkCmdPushConstants and will be be used in all the following draw commands. The catch of the push constants is that there's a much more limited size for them, but 16 uniforms would most likely fit just fine.

[rombust]

Ah, thanks. It looks like my reasoning for the validation log error was incorrect.

The VulkanGraphicContextProvider constructor calls create_descriptor_set_layout() using hard coded limits:

	static constexpr int MAX_TEXTURES = 32;
	static constexpr int MAX_UBOS = 16;
	static constexpr int MAX_SSBOS = 16;

It will better to only create them when required, up to the supported limit. I missed this when looking at the code template.

In addition, it looks like VulkanGraphicContextProvider::flush_descriptors() will need manually rewritten.

To support the sprite shader validation, the code always fills 16 samplers (with dummy 1x1 textures if not given). This certainly is undesirable when using different shaders.

See https://github.com/rombust/ClanLib/blob/d9b98de946483c0b670bd2036431b83ff542a2de/Sources/VK/VK1/vulkan_graphic_context_provider.cpp#L1377

[dpjudas]

It can check what the limits are, but that wasn't really what I was getting at.

Those limits are for the number of bound uniform buffers. Nothing in ClanLib's standard shaders needs 16 uniform buffers. I deducted from your description this must mean that currently you're placing one uniform in one uniform buffer each. If it trying create a layout with the theoretical maximum uniform buffers that is also pretty bad. The driver uses this information to make optimizations and if we tell it we are using 16 when we are only using 1 that means it can't take any shortcuts if any presents themselves.

About the 16 samplers - we did this originally as a speed optimization as binding textures was really slow on older GPUs and OpenGL. Modern GPUs and Vulkan does not have that overhead. Binding textures is very cheap and so is issuing draw calls. If you can simply convince the sprite drawing code to just use 1 sampler that will be just as fast on Vulkan. Haven't looked at the code to see how feasible that is though.

[rombust]

Update:

The examples Basic2D, Font (uses clanUI), Multiwindow and Path have been tested on Windows using these GPU’s with Vulkan validation enabled:

NVIDIA GeForce RTX 4070
NVIDIA Quadro K4000
Intel UHD Graphics 770

The only validation issue is the Intel GPU reporting (in all examples):
Thu Mar 26 14:54:22 2026 UTC [Vulkan] windows_get_device_registry_files: unable to obtain GUID for:2 error:37

I will have a look next week.

On Linux (X11). I have so far only tested Basic2D without validation.

The aim is to not change any existing ClanLib API.

I am hoping this implementation also works on the Raspberry PI. I have yet to test it.

Vulkan is a steep learning curve when I only have an OpenGL mindset. I am drained!