No clear link from Vulkan documentation to GLSL/HLSL equivalents

[Tobski]

It's somewhat tricky to find the relevant shader language specs for a given feature if you don't know what you're looking for in advance - I've heard a few devs/colleagues struggle to find language mappings for these two languages, so would be good if we could try to help that situation somehow.

Perhaps something like adding a link to the GLSL spec repo and the HLSL spir-egg mapping document from the Vulkan registry would be a useful stopgap solution? Longer term if we ever get a "getting started" guide or wiki set up, these should be prominent links in there.

[nsubtil]

We may not be able to discuss this on the phone very soon, so wanted to write down my current thoughts on this.

I've had the same issue when looking through the spec and I agree this is a real problem. However, while having a link to the spec repo by itself seems like a logical first step (and I'm surprised it's not there yet), what I believe would be really helpful here would be linking/cross-referencing the GLSL and HLSL documentation from the Vulkan spec.

Sadly, the GLSL specs are plain text files, which makes it impossible to link to specific sections, so cross-referencing becomes difficult. Tagging @oddhack and @johnkslang to get some feedback here --- would we be able to convert the GLSL specs to a more structured format that would allow linking from the Vulkan spec?

I haven't looked at the HLSL/Spiregg side of things yet. I know their documentation is a lot more structured, so I'm hoping that won't be as much of an issue.

[oddhack]

Conversion is possible but would be a lot of manual labor, of course. Finding the resources to do it would be the hard part, when not much Khronos effort is being spent on GL/ES issues these days. I have a vague recollection that someone in a Google Summer of Code project many years ago, wrote a text extension -> HTML converter, but finding that and getting it functioning and debugged would also be a lot of work.

Most of the extension specs are fairly short, so the benefit of linking to particular places isn't as great as it might be in larger documents. Including something like "As shown in the GL_name extension, under 'Modifications to section N.N of the spec name'" in the visible link text might be a reasonable compromise.

[johnkslang]

The top two specifications involved are the core ESSL/GLSL spec and the Vulkan extension for GLSL. Both are large. The first is already taggable asciidoc, and the other would be relatively easy to convert to asciidoc (not html) since it is already plain text.

[marty-johnson59]

This repository is being archived as it has been replaced with the vulkan.org website and is no longer being maintained (i.e., issues posted here are no longer being addressed ). After reviewing issues posted here, most (if not all) have been resolved or have already been re-opened in Vulkan-Docs (https://github.com/KhronosGroup/Vulkan-Docs) or other repositories for further consideration. Therefore, all issues in this repository will be closed. If you believe your issue has not yet been resolved, please re-open in Vulkan-Docs. Thanks!