Standard location of the webgpu.h header

[eliemichel]

Has there been a position stated about where the webgpu.h should be expected wrt. include paths?

The reason I ask is with regards to the generation/specification of extension headers and in particular the way they should include webgpu.h, as well as questions that arise when sharing code without imposing a build systems (e.g., in Dear ImGui's wgpu backend).

Some elements I could find in practice:

• Currently, our generator adds #include "webgpu.h" when generating extensions, which implies that either my_webgpu_extension.h sits in the very same directory as webgpu.h or this directory is in the include paths. But this has not been tested much and is probably still open to evolution?
• Dawn places its generated header in webgpu/webgpu.h and tends to #include <webgpu/webgpu.h> in examples.
• Same for emscripten
• The question came up in wgpu-native, especially because its is the only implementation that already adopted the dual header scheme (i.e. a separate file for implem-specific extensions), and there was no strong opinion, but it settled for some convenience reason on using #include "webgpu.h" in wgpu.h and placing it in the very same directory as webgpu.h. Both are in a directory called "webgpu" as well.
• After some thought about it in early its developments, I adopted #include <webgpu/webgpu.h> for my programming guide and the associated code because it felt compatible with most examples I could find (and I liked the webgpu/ prefix to regroup potential extensions like c++ wrapper, etc.).

Since all implementation indeed distribute webgpu.h in a directory called "webgpu", should we (a) explicitly state that the preferred way to include the WebGPU native header is through webgpu/webgpu.h and (b) have extension header use #include <webgpu/webgpu.h> in case they are distributed through a different directory?

For some reason my intuition tells me that (a) is a yes and (b) is a no, but feel free to prove me wrong :D

Some other examples:

• gpu.cpp uses #include "webgpu/webgpu.h"
• Another example uses #include "webgpu.h"

[kainino0x]

No, I don't think we've documented it. I think it should be <webgpu/webgpu.h> of course, since Dawn/Emscripten use that :)

[kainino0x]

BTW I would love to also answer the question of where implementations should put their extensions, though this is a bit muddied by the fact that Dawn just puts all of its extensions in the main header right now.
Ideas:
webgpu/webgpu_dawn.h
dawn/webgpu.h
dawn/webgpu_dawn.h

[kainino0x]

For example Dawn could have:

• webgpu/webgpu.h <- verbatim the same as the upstream one
• dawn/webgpu_dawn.h <- just dawn's extensions
• dawn/webgpu.h <- 2-line file that just includes the other two

[eliemichel]

IIRC wgpu-native used to place its header in "wgpu/wgpu.h" but moved it to "webgpu/wgpu.h" because for some weak reason it was easier than changing the #include "webgpu.h" into #include "webgpu/webgpu.h" inside of "wgpu.h". My guess is that it'd be easy to switch to another solution nonetheless (see gfx-rs/wgpu-native#424).

I do not really have a preference between "webgpu/webgpu_dawn.h" (meaning "that's part of webgpu") or "dawn/webgpu_dawn.h" (meaning "that belongs to dawn").

[kainino0x]

Dec 12 meeting:

• CF: Do we need to define this?
• KN: I think typically headers define this for when it's in the system path. Emscripten already has webgpu.h in a "system" path [though it's the Emscripten-specific version of the header].
• #include <webgpu/webgpu.h> sounds good.
• And also of implementations' header extensions?
• LK: Think we shouldn't answer this yet because thinking Dawn should have one combined header instead of core+extension headers.
• KN: Could still say where the combined header should be, and that there should be one. But implementations can really do whatever they want so not really important to say.
• Don't answer this question at least for now.

[eliemichel]

LK: Think we shouldn't answer this yet because thinking Dawn should have one combined header instead of core+extension headers.

My opinion is that it would be very misleading that multiple versions of webgpu.h header exist; I am strongly in favor of making a clear split between what is standard vs what is Dawn-specific. Mixing them in a single one could lead to confusion when documentation/answers on stackoverflow/etc fail at precising that something is implem-specific and we ultimately end up with one implementation taking over the other ones. And that pattern does not seem right to me!

[kainino0x]

It wouldn't necessarily need to be called webgpu.h (though it is currently), and fair point that it could be confusing. It definitely wouldn't be webgpu/webgpu.h. Maybe it should simply be dawn/dawn.h or something.

cc @lokokung

[lokokung]

My thought is that implementation specific things should already have that in their names, i.e. DawnTextureInternalUsageDescriptor or SurfaceSourceCanvasHTMLSelector_Emscripten which should make it obvious that they are extensions in specific implementations versus core.

Also, having multiple versions of webgpu.h will be inevitable anyways because there can be different versions of it as we add new features? And different implementations will likely be at different points of compatibility at different times.