Request for Comments: Use programming language instead of prose for usage statements

The Vulkan Working Group is considering a redesign of the way valid usage statements are written. The idea is to use a programming language instead of prose to improve readability (by programmers) and precision. Your comments are welcome!

Please take a look at the proposal here: Proposal doc for codified VUs by ShabbyX · Pull Request #2043 · KhronosGroup/Vulkan-Docs · GitHub

1 Like

It certainly is ambitious. The holy grail is to just autogenerate validation layers, which are currently continuously incomplete and riddled with human errors.

Not sure if Python is the best.

And not sure if the procedural paradigm is the best. Particularly I don’t like spam of raw ifs and fors. 99 % of usage of for would likely be semantically something like for_each. And 90 % of ifs will be something like to express a parameter is non-optional (non-null). The VUs should strive to express high-level semantics (what things mean), over low-level procedurals (how things are done on CPU).

Additionally not sure about require(). Perhaps the VU should simply be an expression returning true or false?

For example, I would prefer something almost English like:

isWritableAttachment= [](Attachment a){
    a.imageView != VK_NULL_HANDLE
    && a.resolveMode != VK_RESOLVE_MODE_NONE};
onlyWrittenAttachments = []( CArray attachments ){
    filter(attachments, isWritableAttachment) };
hasWritableLayout = [](Attachment a){
     isNotOf( a.layout,
              {VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
               VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL}) };

colorAttachments = a(pColorAttachments, colorAttachmentCount);
std::all_of( onlyWrittenAttachments(colorAttachments),
             hasWritableLayout )

Doing it this way also means some of the common functions, predicates, and other entities can be reused rather than endlessly repeated.

Additionally previously there was a problem that many VUs needed to be moved up the hierarch from the structs. It would be great if this permited VU parametrization, so VU can be at more meaningful place in the spec and also not repeated much. E.g. VkImageSubresourceRange could inherit image parameter, so it can validate its aspectMask parameter against it.

Even ignoring the tortrued C++ syntax, it’s unclear what this all actually means. One nice thing about VUs is that each rule is independent. You can even cite them separately by unique identifier numbers. This jams a bunch of them together, and puts the “for each attachment” part well after the rule that actually does the checking.

The current system has a lot of redundancy, but that redundancy has a purpose.

My broad concern with this idea is how well it will work for VU rules that need non-local information. Rendering functions require doing a lot of checking of the current state, for example. Various extension structure VUs need to "reach out"of the current data structure into sibling structures or even function parameters of the sibling structure.

I use C++, which I kinda like, and assume users of Vulkan would know best. It is not necessarily ideal (given its long history).

It means you can only read the last line, and it is practically English:

all_of( onlyWrittenAttachments(pColorAttachments),
           hasWritableLayout )

“Every Attachment that is writable must have writable layout.”

It for me takes much less to understand code like this than web of raw ifs and fors, which typically is too preoccupied with how things should be executed so it forgets to tell what it means.

Yet that is almost never how it is used. List of VUs is like a checklist one must get through whole. And the repeated prologs get in the way.

It doesn’t. There’s some misunderstanding. This is just recreation of VUID-VkRenderingInfo-colorAttachmentCount-06097 which is one of the first VUs the OP link shows.

PS: it would be nice though if it did. We should ideally iterate over arrays and dereference (potentially nullable) pointers only once. The redundancy is not good for neither the human reader, nor the machine.

Aggreed. I also was in process of mentioning that in edit above. Puting VUs back to the structs it belongs would be great and also reduce pointless repetition.

This topic was automatically closed 183 days after the last reply. New replies are no longer allowed.