Xml spec: Converting C text to attributes

[SilverPhoenix99]

Hi.

Are there any plans to make the xml spec less dependent on the C language?

For example, for const and/or pointer arguments it would be possible to add a type/parameter modifier attribute:

<command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_OUT_OF_HOST_MEMORY,VK_ERROR_OUT_OF_DEVICE_MEMORY">
    <proto><type>VkResult</type> <name>vkCreateFence</name></proto>
    <param><type>VkDevice</type> <name>device</name></param>
    <param modifier="const"><type modifier="pointer">VkFenceCreateInfo</type> <name>pCreateInfo</name></param>
    <param modifier="const" optional="true"><type modifier="pointer">VkAllocationCallbacks</type> <name>pAllocator</name></param>
    <param><type modifier="pointer">VkFence</type> <name>pFence</name></param>
</command>

And for function pointers, it would be possible to wrap a command inside a type:

<type category="funcpointer">
    <command>
        <proto><type>void</type> <name>PFN_vkInternalAllocationNotification</name></proto>
        <param><type modifier="pointer">void</type> <name>pUserData</name></param>
        <param><type>size_t</type> <name>size</name></param>
        <param><type>VkInternalAllocationType</type> <name>allocationType</name></param>
        <param><type>VkSystemAllocationScope</type> <name>allocationScope</name></param>
    </command>
</type>

This would be useful to language bindings, since the definitions would be more aligned with xml, instead of text in between elements, and still without loosing the expressiveness of C.

Related with https://github.com/KhronosGroup/Vulkan-Docs/issues/10

[SilverPhoenix99]

Answer related with https://github.com/KhronosGroup/Vulkan-Docs/issues/6 (specifically https://github.com/KhronosGroup/Vulkan-Docs/issues/6#issuecomment-185013796)

So I need to clarify: The intent is not to have a language agnostic Xml, but to define most common cases (const and pointer) as attributes. Things that are more intrinsic to C, like #define are more complex to define as xml and I'm disregarding those cases.

[oddhack]

I am not planning that at present. I have been down this path in the past and it made life much more difficult. But it's reasonable to have some utility functions in the Python scripts which parse the simplistic amount of C used in the XML and break out this sort of information. All that's needed is enough logic to parse a simple variable declaration containing pointers and arrays and const qualifiers. Hoping someone else will sign up to write that as I'm pretty fully subscribed just keeping up with the release mechanics, for now.

[mdsitton]

Personally I wouldn't want to see a ton of changes that make things drastically different from the gl registry xml, a couple of things here and there would be fine though. edit: This is because i currently have my own (also written in python) registry parser that i want to have compatible with both gl and vulkan. (Took me less time to just write my own than to figure out how to make the official opengl registry parser do what I wanted.)

[oddhack]

@mdsitton it's less the official parser than the official header / docs generation tool, TBH.

It is difficult to accomodate everyone (and still have the result vaguely human readable/editable, which is important to me as the one who does most of the editing). Some Khronos members are enthusiastic about having a JSON representation, but it's actually pretty difficult to mechanically translate the XML to JSON because XML allows multiple identical tags to appear in an enclosing tag, mixed with other content. Someone able to spend more time on JSON than I needs to figure out that translation if it's going to happen.

[mdsitton]

A JSON representation would certainly be interesting to look at but there is a lot of information that needs to be represented not sure if it would actually end up being usable though. I might do some tests on that though.

[SilverPhoenix99]

@mdsitton I understand your point of view, since any other way you would have to deal with two standards. One idea is to keep the C code (const and the *) but also add the modifier attributes redundantly, as to allow compatibility with both specs. Of course, the issue would now be the coherence of the redundant information.

@oddhack I'm aware of the reason why the gl.spec was replaced by the xml spec, which was a very positive shift in respect to language bindings. I do agree with you that a readable xml is impossible for a full C conversion, so I'm trying to restrict it to the common cases. Still, I find it odd that funcpointer types are so close to C, but struct types are almost only xml.

I believe that the following, although it breaks compatibility with OpenGL spec (sorry @mdsitton!), is still readable, but also makes it much easier to parse. Note that I only added xml elements around text. The text is still the same, so as not to go overboard and convert the spec into full xml.

<type category="funcpointer">typedef 
    <command>
        <proto><type>void</type> (VKAPI_PTR *<name>PFN_vkFreeFunction</name></proto>)(
        <param><type>void</type>*            <name>pUserData</param>,
        <param><type>void</type>*            <name>pMemory</param>);
    </command>
</type>

But, of course, the decision is yours and the Group. :) I'm just defending my reasoning, because I'm confident there's a middle ground that we can agree, where metadata can still be added.

[SilverPhoenix99]

Linking to https://github.com/KhronosGroup/Vulkan-Docs/issues/83, since it's essentially the same issue.

[elfring]

And for function pointers, it would be possible to wrap a command inside a type:

I would prefer an other design approach. I have got the impression that a part of the mentioned data processing difficulties comes from the specification of a mixed data structure for the parameters and function return types of commands in the RELAX NG schema.

…
        mixed {
            element type { TypeName } ? ,
            element name { text }
        }
…

I imagine that the desired data processing can become a bit easier if these elements would be converted into attributes for the elements "param" and "proto". How do you think about such a data model transformation?

[elfring]

This would be useful to language bindings, since the definitions would be more aligned with xml, instead of text in between elements, and still without loosing the expressiveness of C.

• How do you think about to reduce the usage of mixed XML content for any "special" cases in the provided Vulkan data model?
• Would you like to support any decomposition efforts so that higher level data structures can provide various benefits for safer software developments?

[zyrolasting]

Joining this topic a bit late from duplicate #930. It seems like there is no single representation that can elegantly express all interests at once, so I'm curious about a subject-oriented approach.

I am not planning that at present. I have been down this path in the past and it made life much more difficult. But it's reasonable to have some utility functions in the Python scripts which parse the simplistic amount of C used in the XML and break out this sort of information. [...] Hoping someone else will sign up to write that as I'm pretty fully subscribed just keeping up with the release mechanics, for now.

@oddhack I volunteer since this issue has been causing problems for me. Are you the best contact for historical context and tribal knowledge that I won't find in published materials?