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 ⭐.