Add dynamic primitive clipping example

[pumexx]

Description

This example demonstrates how to use primitive clipping through dynamic pipeline state.

Dynamic properties required to implement this example are defined in VK_EXT_extended_dynamic_state3 extension and in chapter 27.4 of the Vulkan specification ( "Primitive Clipping" ).

General Checklist:

Please ensure the following points are checked:

• My code follows the coding style
• I have reviewed file licenses
• I have commented any added functions (in line with Doxygen)
• I have commented any code that could be hard to understand
• My changes do not add any new compiler warnings
• My changes do not add any new validation layer errors or warnings
• I have used existing framework/helper functions where possible
• My changes do not add any regressions
• I have tested every sample to ensure everything runs correctly
• This PR describes the scope and expected impact of the changes I am making

Note: The Samples CI runs a number of checks including:

• I have updated the header Copyright to reflect the current year (CI build will fail if Copyright is out of date)
• My changes build on Windows, Linux, macOS and Android. Otherwise I have documented any exceptions

Sample Checklist

If your PR contains a new or modified sample, these further checks must be carried out in addition to the General Checklist:

• I have tested the sample on at least one compliant Vulkan implementation
• If the sample is vendor-specific, I have tagged it appropriately
• I have stated on what implementation the sample has been tested so that others can test on different implementations and platforms
• Any dependent assets have been merged and published in downstream modules
• For new samples, I have added a paragraph with a summary to the appropriate chapter in the samples readme
• For new samples, I have added a tutorial README.md file to guide users through what they need to know to implement code using this feature. For example, see conditional_rendering
• For new samples, I have added a link to the Antora navigation so that the sample will be listed at the Vulkan documentation site

[pumexx]

There's one error present in this example: when I switch primitive clipping off in a GUI and subsequently code calls vkCmdSetDepthClipEnableEXT(cmd, VK_FALSE), the primitive clipping is still enabled.
At first I thought that it may be an error in nVidia driver. But AMD driver shows the same error. I went through Vulkan specification checking other possible paths that may turn the primitive clipping on and did not find any clue on why this error happens.

I modified shader_object example to use vkCmdSetDepthClipEnableEXT and got the same error - calls to this command are ignored.

I also consulted my friend from Vulkan CTS group and we established that vkCmdSetDepthClipEnableEXT command is not tested at all ( to be precise: function is called once in tests, but gl_ClipDistance builtin is not used in the shaders used by the test ).

For me it looks like vkCmdSetDepthClipEnableEXT command was not implemented in both NVidia and AMD drivers at all.
Both drivers just use the results of 'gl_ClipDistance' calculation without checking additional condition set by vkCmdSetDepthClipEnableEXT.
It may be because primitive clipping is a very rare animal.

I plan to create an issue in Vulkan CTS project, so that vkCmdSetDepthClipEnableEXT has proper test coverage.

[SaschaWillems]

Thank you very much for this sample. New samples are always very much appreciated :)

Right now CI fails due to outdated copyrights and problems with clang format. Once those are fixed, we'll start reviewing it. If you need any assistance, feel free to ping.

[SaschaWillems]

There's one error present in this example: when I switch primitive clipping off in a GUI and subsequently code calls vkCmdSetDepthClipEnableEXT(cmd, VK_FALSE), the primitive clipping is still enabled.
At first I thought that it may be an error in nVidia driver. But AMD driver shows the same error. I went through Vulkan specification checking other possible paths that may turn the primitive clipping on and did not find any clue on why this error happens.

This seems to work fine for me. If I uncheck "use clipping", it looks like this on my 4070 with recent Vulkan developer drivers:

[SaschaWillems]

Looks good to me so far.

I only have a few very minor remarks added as comments.

Thanks for adding this new sample :)

[pumexx]

This seems to work fine for me. If I uncheck "use clipping", it looks like this on my 4070 with recent Vulkan developer drivers:

In that case we should see the whole Utah teapot as "blue". But it looks like a call to vkCmdSetDepthClipEnableEXT(cmd, VK_FALSE) is ignored.

I could hide "use clipping" checkbox in order to disguise the error (at least temporarily), but I think this sample may be a good place for field testing by driver developers.

[SaschaWillems]

This oddly still fails with CI checks. @tomadamatkinson: Any idea? It seems to fail at files not even part of this PR

[pumexx]

This oddly still fails with CI checks. @tomadamatkinson: Any idea? It seems to fail at files not even part of this PR

That's why I didn't fix it yet. I am afraid of avalanche of another wrong copyright checks.

[pdaniell-nv]

Reading the comments in this PR it makes me wonder if ClipDistance is being confused with depth clipping, which are different steps in the primitive clipping part of the pipeline. User defined clip distances are enabled/disable by the presence of ClipDistance decorated outputs in the shader, and are independent to the depth clamp and depth clip pipeline states. In other words, setting vkCmdSetDepthClipEnableEXT(VK_FALSE) or vkCmdSetDepthClipEnableEXT(VK_TRUE) won't have any affect on any ClipDistance specified in the shader and their operation.

[gary-sweet]

I'm surprised this even ran for me since we don't support some of the features being used here. I suspect you may be missing some checks. See https://vulkan.gpuinfo.org/displayreport.php?id=27052 for the full set of device support on the board I'm using.

I also see some validation errors which are likely related:
[error] [framework/core/instance.cpp:50] -1876993556 - VUID-VkDeviceCreateInfo-pNext-pNext: Validation Error: [ VUID-VkDeviceCreateInfo-pNext-pNext ] Object 0: handle = 0x2a78ced0, type = VK_OBJECT_TYPE_INSTANCE; | MessageID = 0x901f59ec | vkCreateDevice(): pCreateInfo->pNext includes a pointer to a VkPhysicalDeviceDepthClipEnableFeaturesEXT, but when creating VkDevice, the parent extension (VK_EXT_depth_clip_enable) was not included in ppEnabledExtensionNames.

[error] [framework/core/instance.cpp:50] 115483881 - VUID-VkShaderModuleCreateInfo-pCode-08740: Validation Error: [ VUID-VkShaderModuleCreateInfo-pCode-08740 ] | MessageID = 0x6e224e9 | vkCreateGraphicsPipelines(): pCreateInfos[0].pStages[0] SPIR-V Capability ClipDistance was declared, but one of the following requirements is required (VkPhysicalDeviceFeatures::shaderClipDistance). The Vulkan spec states: If pCode is a pointer to SPIR-V code, and pCode declares any of the capabilities listed in the SPIR-V Environment appendix, one of the corresponding requirements must be satisfied (https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#VUID-VkShaderModuleCreateInfo-pCode-08740)

[pumexx]

Reading the comments in this PR it makes me wonder if ClipDistance is being confused with depth clipping, which are different steps in the primitive clipping part of the pipeline.

You are right @pdaniell-nv . I mixed up these two steps.

I was looking for some external switch that may cause gl_ClipDistance computations to be ignored like we can ignore depth values computed in a shader by turning off depth writing and depth testing in a graphics pipeline. vkCmdSetDepthClipEnableEXT looked like a best match, especially because it's defined in a Vulkan specification in the same chapter right after primitive clipping which uses gl_ClipDistance.

I decoupled these two features in my sample and now it presents both of them. I also described both of these features in README.adoc and I specifically emphasized that these two are distinct features. I hope this helps to solve potential user confusion.

@gary-sweet :

I'm surprised this even ran for me since we don't support some of the features being used here. I suspect you may be missing some checks.

I added additional check: if shaderClipDistance feature is not present then application is terminated.

@SaschaWillems: I fixed these two strange copyright checks in a code that I did not touch and now I see that there is some conflict to resolve. Great...

[SaschaWillems]

@tomadamatkinson: can you take a look at this? Having to change copyrights on files not actually touched by a PR is something we shouldn't require people to do.

[SaschaWillems]

LGTM and works fine for me on Win11 and an RTX4070

[asuessenbach]

This is, what VVL tells me:
Attempting to enable extension VK_EXT_depth_clip_enable, but this extension is intended to support D3D emulation layers, and applications ported from D3D, by adding functionality specific to D3D and it is strongly recommended that it be otherwise avoided.
Is that valid? Does anybody know, why it should not be used?

[Mateusz-Kowalewski-Mobica]

@SaschaWillems @asuessenbach Can I request for your reviews for current state of this sample?
I merge it with main after PR#910 submission, so it is prepared for new approach.
I takeover responsibility of it from Paweł.

[SaschaWillems]

Works fine for me on Windows 11 with an NVIDIA RTX 4070.

This is a really nice example. Thank you very much 👍🏻

[asuessenbach]

Isn't this text part of a different PR?

[Mateusz-Kowalewski-Mobica]

Yes, but this is weird. As you see I didn't change any letter even line is the same. After that line I added new line with dynamic primitive clipping. To be more elegant I can fix that to doesn't have that line in git diff.

[marty-johnson59]

Merging - 3 approvals