Naming conventions for extension structs and implementation-specific extensions

[kainino0x]

We should define some naming conventions for both standardized extension structs and implementation-specific extensions. Right now we have the following (inconsistent) names:

WGPUPrimitiveState extensions:
WGPUPrimitiveDepthClipControl

WGPURenderPassDescriptor extensions:
WGPURenderPassDescriptorMaxDrawCount

WGPUShaderModuleDescriptor extensions:
WGPUShaderModuleSPIRVDescriptor
WGPUShaderModuleWGSLDescriptor

WGPUSurfaceDescriptor extensions:
WGPUSurfaceDescriptorFromAndroidNativeWindow
WGPUSurfaceDescriptorFromCanvasHTMLSelector
WGPUSurfaceDescriptorFromMetalLayer
WGPUSurfaceDescriptorFromWaylandSurface
WGPUSurfaceDescriptorFromWindowsHWND
WGPUSurfaceDescriptorFromXcbWindow
WGPUSurfaceDescriptorFromXlibWindow

Additionally for Dawn we might want things like WGPUSomeDescriptorNewFeatureDAWN? (though idk what the naming would be for wgpu-native)

[Kangz]

For ergonomics it seems that typing Descriptor all the time is annoying. So I'd favor a rule like:

• Take the name of the chain root, remove Descriptor, State or other common words
• Optionally add a name to scope to a project / vendor Dawn, Wgpu, ...
• Add the extra words.

So the list would become:

WGPUPrimitiveState extensions:
WGPUPrimitiveDepthClipControl

WGPURenderPassDescriptor extensions:
WGPURenderPassMaxDrawCount

WGPUShaderModuleDescriptor extensions:
WGPUShaderModuleSPIRV
WGPUShaderModuleWGSL

WGPUSurfaceDescriptor extensions:
WGPUSurfaceFromAndroidNativeWindow
WGPUSurfaceFromCanvasHTMLSelector
WGPUSurfaceFromMetalLayer
WGPUSurfaceFromWaylandSurface
WGPUSurfaceFromWindowsHWND
WGPUSurfaceFromXcbWindow
WGPUSurfaceFromXlibWindow

WDYT?

[kainino0x]

webgpu.h meeting resolution (OUTDATED):

• fold DepthClipControl into PrimitiveState
• drop Descriptor from chained struct names as proposed above
• add Wgpu or Dawn at the end for implementation-specific extensions

See also #214 about enum range reservations.

[kainino0x]

Feedback that eliding "Descriptor" from the extension struct names is confusing:
https://chromium-review.googlesource.com/c/chromium/src/+/5691772/comment/25f7fc96_8d6b6f12/

[kainino0x]

Jul 18 meeting:

• Got feedback that new names are hard to understand
• WGPUSurfaceFromCanvasHTMLSelectorDescriptor
• WGPUSurfaceFromCanvasHTMLSelector
• WGPUSurfaceDescriptorFromCanvasHTMLSelector
• WGPUSurfaceDescriptor_FromCanvasHTMLSelector
  • With this in C++ we could actually namespace it?
• KN: Try to give them descriptive names that don't depend on the descriptor they're attached to? (Docs tell you what they're attached to.)
• CF: Vulkan style.
• Brainstorm:
• WGPUCanvasHTMLSelector
• WGPUExtCanvasHTMLSelector
• WGPUSurfaceSourceCanvasHTMLSelector
• WGPUSurfaceSourceAndroidNativeWindow
• WGPUSurfaceSourceMetalLayer
• WGPUShaderSourceWGSL
• WGPUShaderSourceSPIRV <- current caps style
• WGPUShaderSourceSPIRV_EXT
• WGPUShaderSourceGLSLWgpu
• WGPUShaderSourceGLSL_Wgpu ?? doesn’t look right
• WGPUShaderSourceGLSL_WGPU
• WGPUShaderSourceGLSL_wgpu ?? Feels like typo
• WGPUShaderSourceGLSL_DAWN
• WGPUShaderSourceGLSL_GFXRS
• WGPUShaderSourceGLSL_RUSTYGRAPHICSMAGES
• WGPUShaderSourceGLSL_Dawn
• WGPUShaderSourceGLSL_NATIVE
• WGPUShaderSourceGLSL_STD
• WGPUShaderSourceGLSL_EMSCRIPTEN ??
• WGPUShaderSourceGlslWgpu <- proposed caps style?
• Propose the naming conventions in bold above, get feedback
  • Also need to update #214

(I'll expand out that proposal in a followup comment)

[kainino0x]

Rough proposal:

WGPURenderPassDescriptor extensions:
WGPURenderPassMaxDrawCount or WGPUMaxDrawCount

WGPUShaderModuleDescriptor extensions:
WGPUShaderSourceSPIRV
WGPUShaderSourceWGSL

WGPUSurfaceDescriptor extensions:
WGPUSurfaceSourceAndroidNativeWindow
WGPUSurfaceSourceCanvasHTMLSelector_Emscripten (see #214 (comment))
WGPUSurfaceSourceMetalLayer
WGPUSurfaceSourceWaylandSurface
WGPUSurfaceSourceWindowsHWND
WGPUSurfaceSourceXcbWindow or WGPUSurfaceSourceXCBWindow
WGPUSurfaceSourceXlibWindow

Other examples of how extensions could be named:

WGPUPrimitiveState extensions:
WGPUPrimitiveDepthClipControl or WGPUDepthClipControl (we are getting rid of this but this is what it would look like)

WGPUShaderModuleDescriptor extensions:
WGPUShaderSourceGLSL_WGPU
WGPUShaderSourceGLSL_Dawn

[beaufortfrancois]

WGPUPrimitiveState extensions:
WGPUPrimitiveDepthClipControl or WGPUDepthClipControl

My understanding was that we'd fold DepthClipControl into PrimitiveState with #311
@kainino0x Did I misunderstand?

[Kangz]

Yes we're folding it, but that's just for the explanation of the new naming rules.

[kainino0x]

Oh yes, I intended to note that but forgot. Edited above.

[beaufortfrancois]

I believe we can close this issue after #320 gets merged.

[kainino0x]

You're right, thanks!
Dawn bug is https://crbug.com/42241174

[kainino0x]

Applying this naming convention to Dawn we are finding we don't know how to name:

• New enums, and their enum values.
  WGPUMyEnumType_Dawn
WGPUMyEnumType_Dawn_MyValue? suffix on enum name, but it ends up in the middle.
  WGPUMyEnumType_MyValue_Dawn? suffix at the end of each thing ⭐
  WGPUMyEnumType_Dawn_MyValue_Dawn? (lol)
  wgpu::MyEnumType_Dawn::MyValue?
  wgpu::dawn::MyEnumType::MyValue? ⭐

• Methods of new objects and FreeMembers functions of new structs
  WGPUAdapterPropertiesMemoryHeaps
wgpuAdapterPropertiesMemoryHeaps_DawnFreeMembers()?
  wgpuAdapterPropertiesMemoryHeapsFreeMembers_Dawn()? ⭐

  WGPUMyObject_Dawn
wgpuMyObject_DawnMyMethod()?? (bad)
  wgpuMyObjectMyMethod_Dawn()? ⭐
  wgpu::MyObject_Dawn::MyMethod()?
  wgpu::dawn::MyObject::MyMethod()? ⭐

Marked the ones I like personally with ⭐.

[Kangz]

Adding the namespace in C++ is cool, but could be mildly difficult to do in Dawn, though it's not breaking for webgpu.h so it's ok to do later. That said I really don't understand why we need a _ to separate the extension block name from the rest of the name. There are likely to be very few blocks, and they will have clear names like <vendor> or "Native". IMHO it should be a prefix to go from general (WGPU) to more specific. The block is the second most general thing after WGPU. Subjectively it makes things easy to ready while not looking weird with random underscores:

New enums and their enum values:

• WGPUDawnMyEnumType
• WGPUDawnMyEnumType_MyValue
• WGPUEnumType_DawnMyValue
• wgpu::DawnEnumType
• wgpu::DawnEnumType::MyValue
• wgpu::EnumType::DawnMyValue
• Alternatively we could do the namespacing in C++ at some point wgpu::dawn::EnumType::MyValue.

New methods and new objects

• WGPUDawnAdapterPropertiesMemoryHeaps
• wgpuDawnAdapterPropertiesMemoryHeaps_FreeMembers()
• WGPUDawnMyObject
• wgpuDawnMyObject_MyMethod()
• wgpuObjectType_DawnMethod()
• wgpu::DawnMyObject
• wgpu::DawnMyObject::MyMethod()
• wgpu::MyObject::DawnMethod()
• Likewise we could namespace in C++ wgpu::dawn::MyObject.

[kainino0x]

IMHO it should be a prefix to go from general (WGPU) to more specific.

The Khronos-like style makes it so when something gets promoted to core, only the suffix is removed. I don't have that much preference, but we do have the problem that one of the blocks is for wgpu so we would have WGPUWgpuFoo and wgpuWgpuBar()

[kainino0x]

wgpu-native's suffix could maybe change to wgpurs or gfxrs or something. (or wgpunative but that's still very confusing)

[Kangz]

TBH wgpuWgpu is weird but not a big deal.

[beaufortfrancois]

Just wanted to check in and see if we've decided on a naming convention yet.

[eliemichel]

FWIW, my personal opinion: Spontaneously I would have opted for @Kangz' proposal (and agree that a wgpuWgpu prefix is only a minor issue, and really not the only case where having the project called "wgpu" is confusing). I see the point about the Khronos-like style, but is it used anywhere else in WebGPU, or are there any specific reasons to adopt it? How does Vulkan handle naming for extensions that add enum values, or new enums?

[kainino0x]

Nov 25 meeting:

• almost totally missed putting this on the agenda
• discussion: (definitely don't want double suffix or suffix stuck in the middle)
• OK with either, no real opinion:
  • WGPUDawnMyEnumType + WGPUDawnMyEnumType_MyValue
  • WGPUMyEnumType_Dawn + WGPUMyEnumType_MyValue_Dawn

Dawn hasn't implemented suffixes yet, and I checked and wgpu-native has not yet either.
(Dawn naming is ad hoc; wgpu-native has its extensions in a separate header.)

So @Kangz since you prefer WGPUDawnMyEnumType_MyValue we may as well go with that (wgpu-native will probably use WGPUWgpuMyEnumType_MyValue)

---

I see the point about the Khronos-like style, but is it used anywhere else in WebGPU, or are there any specific reasons to adopt it?

The only specific reason I see to adopt it is that the un-suffixed version of the name (if something becomes core) is exactly the same except for the very end. But that's not significantly different from removing the prefix between WGPU and the rest of the name. Otherwise just because it is familiar to GL/Vulkan developers.

How does Vulkan handle naming for extensions that add enum values, or new enums?

I was pretty sure about this but I should have checked :) Vulkan does this when adding a new enum:
VkPerformanceCounterUnitKHR
VK_PERFORMANCE_COUNTER_UNIT_GENERIC_KHR

I suppose we could have inferred we wanted to use that style from the fact that we said "vulkan style", but we came to a different conclusion anyway, so no problem.

[kainino0x]

Updated #214 accordingly

[kainino0x]

Just thinking a little bit more about adding new values to existing enums and new methods to existing objects, they still get sandwiched which I like a bit less than having suffixes always at the end.

Also wanted to point out:

• wgpuDawnAdapterPropertiesMemoryHeaps_FreeMembers()
• wgpuDawnMyObject_MyMethod()
• wgpuObjectType_DawnMethod()

We don't currently separate the type name from the method name so this would look instead like

• wgpuDawnAdapterPropertiesMemoryHeapsFreeMembers()
• wgpuDawnMyObjectMyMethod()
• wgpuObjectTypeDawnMyMethod() <- fine but not the best

... unless we insert the underscores specifically for the case where we are adding methods to existing objects.

[Kangz]

Yeah I think wgpuBufferDawnClearWithDouble (or w/e) is pretty clear that it's on WGPUBuffer and a Dawn method name. The examples provided above don't use any concrete name which makes it harder to separate the parts, but with wgpuNounDawnVerb it's pretty clear what's happening.

[kainino0x]

Ack.

[kainino0x]

To go through everything, for the record, does this seem right?

wgpuPrefixNewFunction

WGPUPrefixNewObject
wgpuPrefixNewObjectNewMethod
wgpuOldObjectPrefixNewMethod

WGPUPrefixNewEnum
WGPUPrefixNewEnum_OldValue
WGPUOldEnum_PrefixNewValue

WGPUPrefixNewStruct

WGPUPrefixNewBitflagType
WGPUPrefixNewBitflagType_NewValue
WGPUOldBitflagType_PrefixNewValue

WGPUPrefixNewCallback

WGPU_PREFIX_NEW_CONSTANT

[eliemichel]

To go through everything, for the record, does this seem right?

It does!

[kainino0x]

I totally forgot the code generator actually implements the suffixing, so we need to fix that. (It's not used in this repo so it doesn't affect the core webgpu.h.)