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.