[PATCH vkd3d 5/5] include: Document struct vkd3d_shader_interface_info.

[Henri Verbeet]

On Thu, 27 Aug 2020 at 23:38, Zebediah Figura <z.figura12 at gmail.com> wrote:
> >> +/**
> >> + * A chained structure describing the correspondence between source and target
> >> + * bindings of a compiled shader. This structure consists of several similar
> >> + * arrays of structures, each element of which describes a single mapping from
> >> + * a DXBC binding descriptor to a SPIR-V binding descriptor.
> >> + *
> > Like above, think of it as describing the interface between the shader
> > (either source or target) and the target environment. (In some ways
> > that's equivalent to describing a mapping between the source and
> > target shaders of course, but the specifics depend on the target
> > shader type.)
>
> I might be overthinking, but describing it in such terms seems a little
> too abstract, such that it's not clear what exactly should get put in
> this structure. I'll try to come up with a more detailed compromise...
>
It's probably one of those things that would benefit from a couple of
concrete examples.

> Incidentally, the terminology used in dependent structures seems pretty
> closely tied to DXBC -> SPIR-V, and so I was inclined to reflect that in
> the documentation. I'm not sure if there's an intent for this structure
> to be more generic (aside from DXBC -> GLSL, it's not obvious to me what
> it'd be used for, unless we're for some reason interested in compiling
> to DXBC or between GLSL and SPIR-V), but perhaps using different field
> names would help (e.g. not differentiating "space" and "set", or "index"
> and "binding").
>
It's more D3D -> Vulkan, but yes, there's that. The terminology here
could probably do with a review, but note that e.g. register spaces
and descriptor sets aren't quite equivalents.

In terms of target environments, it's mostly OpenGL and Vulkan, which
implies SPIR-V and GLSL. There may also be a case to be made for a
Metal/MSL target. In theory it could also be used for remapping
resource bindings for D3D targets (i.e., with HLSL -> dxbc-tpf, or
even dxbc-tpf -> dxbc-tpf); I'm not sure whether there's a practical
use for that though.