gen: extended headers (#270)

* gen-check: show better error in CI * Generation & Validation for multiple yamls * enum extensions * yaml order matters * add readme section * comments * object extensions * bitflag extensions * add implicit suffix & namespaces * specify namespace in yaml
webgpu-native · Mar 3, 2024 · da37690 · da37690
1 parent 3c31706
commit da37690
Show file tree

Hide file tree

Showing 9 changed files with 462 additions and 196 deletions.
diff --git a/Makefile b/Makefile
@@ -4,4 +4,8 @@ gen: schema.json webgpu.yml
 	go run ./gen -schema schema.json -yaml webgpu.yml -header webgpu.h
 
 gen-check: gen
-	@git diff --quiet -- webgpu.h || { git diff -- webgpu.h; exit 1; }
+	@git diff --quiet -- webgpu.h || {                                                      \
+		echo "error: The re-generated header from yml doesn't match the checked-in header"; \
+		git diff -- webgpu.h;                                                               \
+		exit 1;                                                                             \
+	}
diff --git a/gen/README.md b/gen/README.md
@@ -2,6 +2,18 @@
 
 The generator for generating `webgpu.h` header and other extension headers or implementation specific headers from the yaml spec files.
 
+# Generate implementation specific header
+
+The generator also allows generating custom implementation specific headers that build on top of `webgpu.h` header. The generator accepts the combination of `-yaml` & `-header` flags in sequence, which it uses to validate the specifications and then generate their headers.
+
+For example, if `wgpu.yml` contains the implementation specific API, the header can be generated using:
+
+```shell
+> go run ./gen -schema schema.json -yaml webgpu.yml -header webgpu.h -yaml wgpu.yml -header wgpu.h
+```
+
+Since the generator does some duplication validation, the order of the files matter, so generator mandates the core `webgpu.yml` to be first in the sequence.
+
 # yaml spec
 
 ### Types

diff --git a/gen/cheader.tmpl b/gen/cheader.tmpl
@@ -1,7 +1,7 @@
 {{- MCommentN .Copyright 0}}
 
-#ifndef {{.Name | ConstantCase}}_H_
-#define {{.Name | ConstantCase}}_H_
+#ifndef {{.HeaderName | ConstantCase}}_H_
+#define {{.HeaderName | ConstantCase}}_H_
 
 #if defined(WGPU_SHARED_LIBRARY)
 #    if defined(_WIN32)
@@ -37,7 +37,17 @@
 #define WGPU_NULLABLE
 #endif{{"\n" -}}
 
-{{if eq .Name "webgpu"}}
+{{- if ne .Name "webgpu"}}
+#if !defined(__WGPU_EXTEND_ENUM)
+#ifdef __cplusplus
+#define __WGPU_EXTEND_ENUM(E, N, V) static const E N = E(V)
+#else
+#define __WGPU_EXTEND_ENUM(E, N, V) static const E N = (E)(V)
+#endif
+#endif // !defined(__WGPU_EXTEND_ENUM)
+{{ end}}
+
+{{- if eq .Name "webgpu"}}
 #include <stdint.h>
 #include <stddef.h>
 {{else}}
@@ -46,8 +56,8 @@
 
 {{- if .Constants}}
 {{-   range .Constants}}
-{{- MComment .Doc 0}}
-#define WGPU_{{.Name | ConstantCase}} ({{.Value | CValue}})
+{{-     MComment .Doc 0}}
+#define WGPU_{{.Name | ConstantCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}} ({{.Value | CValue}})
 {{-   end}}
 {{  end}}
 
@@ -59,61 +69,51 @@ typedef uint32_t WGPUBool;
 {{- if .Objects}}
 {{-   range .Objects}}
 {{-     if not .IsStruct}}
-typedef struct WGPU{{.Name | PascalCase}}Impl* WGPU{{.Name | PascalCase}} WGPU_OBJECT_ATTRIBUTE;
+typedef struct WGPU{{.Name | PascalCase}}{{$.ExtSuffix}}Impl* WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} WGPU_OBJECT_ATTRIBUTE;
 {{-     end}}
 {{-   end}}
 {{  end}}
 
 {{- if .Structs}}
 // Structure forward declarations
 {{-   range .Structs}}
-struct WGPU{{.Name | PascalCase}};
+struct WGPU{{.Name | PascalCase}}{{$.ExtSuffix}};
 {{-   end}}
 {{  end}}
 
-{{- range $entry := .Enums}}
-{{-   MComment .Doc 0}}
-typedef enum WGPU{{.Name | PascalCase}} {
-{{-   range $entryIndex, $_ := .Entries}}
-{{-     MComment .Doc 4}}
-{{-     $entryValue := 0}}
-{{-     if eq .Value ""}}
-{{-       $entryValue = $entryIndex}}
-{{-     else}}
-{{-       $entryValue = ParseUint .Value 16}}
+{{- range $enum := .Enums}}
+{{-   if .Extended}}
+{{-     range $entryIndex, $_ := .Entries}}
+__WGPU_EXTEND_ENUM(WGPU{{$enum.Name | PascalCase}}, WGPU{{$enum.Name | PascalCase}}_{{.Name | PascalCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}}, {{EnumValue $.EnumPrefix $enum $entryIndex}});
+{{-     end}}
+{{-   else}}
+{{-     MComment .Doc 0}}
+typedef enum WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} {
+{{-     range $entryIndex, $_ := .Entries}}
+{{-       MComment .Doc 4}}
+    WGPU{{$enum.Name | PascalCase}}_{{.Name | PascalCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}} = {{EnumValue $.EnumPrefix $enum $entryIndex}},
 {{-     end}}
-    WGPU{{$entry.Name | PascalCase}}_{{.Name | PascalCase}} = {{printf "%s%.4X," $.EnumPrefix $entryValue}}
+    WGPU{{$enum.Name | PascalCase}}_Force32{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}} = 0x7FFFFFFF
+} WGPU{{$enum.Name | PascalCase}}{{$.ExtSuffix}} WGPU_ENUM_ATTRIBUTE;
 {{-   end}}
-    WGPU{{.Name | PascalCase}}_Force32 = 0x7FFFFFFF
-} WGPU{{.Name | PascalCase}} WGPU_ENUM_ATTRIBUTE;
 {{  end}}
 
-{{- range $entry := .Bitflags}}
-{{-   MComment .Doc 0}}
-typedef enum WGPU{{.Name | PascalCase}} {
-{{-   range $entryIndex, $_ := .Entries}}
-{{-     MComment .Doc 4}}
-{{-     $entryValue := ""}}
-{{-     $valueCombination := .ValueCombination}}
-{{-     range $valueIndex, $v := .ValueCombination}}
-{{-       $v = printf "WGPU%s_%s" ($entry.Name | PascalCase) ($v | PascalCase)}}
-{{-       if IsLast $valueIndex $valueCombination}}
-{{-         $entryValue = print $entryValue $v}}
-{{-       else}}
-{{-         $entryValue = print $entryValue $v " | "}}
-{{-       end}}
-{{-     else}}
-{{-       if eq .Value ""}}
-{{-         $entryValue = printf "0x%.8X" (BitFlagValue $entryIndex)}}
-{{-       else}}
-{{-         $entryValue = printf "0x%.8X" (ParseUint .Value 64)}}
-{{-       end}}
+{{- range $bitflag := .Bitflags}}
+{{-   if .Extended}}
+{{-     range $entryIndex, $_ := .Entries}}
+__WGPU_EXTEND_ENUM(WGPU{{$bitflag.Name | PascalCase}}, WGPU{{$bitflag.Name | PascalCase}}_{{.Name | PascalCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}}, {{BitflagValue $bitflag $entryIndex}});
 {{-     end}}
-    WGPU{{$entry.Name | PascalCase}}_{{.Name | PascalCase}} = {{$entryValue}},
+{{-   else}}
+{{-     MComment .Doc 0}}
+typedef enum WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} {
+{{-     range $entryIndex, $_ := .Entries}}
+{{-       MComment .Doc 4}}
+    WGPU{{$bitflag.Name | PascalCase}}_{{.Name | PascalCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}} = {{BitflagValue $bitflag $entryIndex}},
+{{-     end}}
+    WGPU{{$bitflag.Name | PascalCase}}_Force32{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}} = 0x7FFFFFFF
+} WGPU{{$bitflag.Name | PascalCase}}{{$.ExtSuffix}} WGPU_ENUM_ATTRIBUTE;
+typedef WGPUFlags WGPU{{$bitflag.Name | PascalCase}}Flags{{$.ExtSuffix}} WGPU_ENUM_ATTRIBUTE;
 {{-   end}}
-    WGPU{{.Name | PascalCase}}_Force32 = 0x7FFFFFFF
-} WGPU{{.Name | PascalCase}} WGPU_ENUM_ATTRIBUTE;
-typedef WGPUFlags WGPU{{.Name | PascalCase}}Flags WGPU_ENUM_ATTRIBUTE;
 {{  end}}
 
 {{- if eq .Name "webgpu"}}
@@ -122,15 +122,15 @@ typedef void (*WGPUProc)(void) WGPU_FUNCTION_ATTRIBUTE;
 
 {{- range .FunctionTypes}}
 {{-   MComment .Doc 0}}
-typedef {{FunctionReturns .}} (*WGPU{{.Name | PascalCase}})({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE;
+typedef {{FunctionReturns .}} (*WGPU{{.Name | PascalCase}}{{$.ExtSuffix}})({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE;
 {{- end}}
 
 {{- if .Objects}}
 {{    range $object := .Objects}}
 {{-     range $method := .Methods}}
 {{-       if .ReturnsAsync}}
 {{-         MComment .Doc 0}}
-typedef void (*WGPU{{$object.Name | PascalCase}}{{$method.Name | PascalCase}}Callback)({{CallbackArgs .}}) WGPU_FUNCTION_ATTRIBUTE;
+typedef void (*WGPU{{$object.Name | PascalCase}}{{$method.Name | PascalCase}}Callback{{$.ExtSuffix}})({{CallbackArgs .}}) WGPU_FUNCTION_ATTRIBUTE;
 {{-       end}}
 {{-     end}}
 {{-   end}}
@@ -148,9 +148,9 @@ typedef struct WGPUChainedStructOut {
 } WGPUChainedStructOut WGPU_STRUCTURE_ATTRIBUTE;
 {{  end}}
 
-{{- range .Structs}}
+{{- range $struct := .Structs}}
 {{-   MComment .Doc 0}}
-typedef struct WGPU{{.Name | PascalCase}} {
+typedef struct WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} {
 {{-   if eq .Type "base_in" }}
     WGPUChainedStruct const * nextInChain;
 {{-   else if eq .Type "base_out" }}
@@ -160,17 +160,10 @@ typedef struct WGPU{{.Name | PascalCase}} {
 {{-   else if eq .Type "extension_out"}}
     WGPUChainedStructOut chain;
 {{-   end}}
-{{-   range .Members}}
-{{-     if IsArray .Type}}
-    size_t {{.Name | CamelCase | Singularize}}Count;
-{{-       MComment .Doc 4}}
-    {{ArrayType .Type .Pointer}} {{.Name | CamelCase}};
-{{-     else}}
-{{-       MComment .Doc 4}}
-    {{if .Optional}}WGPU_NULLABLE {{end}}{{CType .Type .Pointer}} {{.Name | CamelCase}};
-{{-     end}}
+{{-   range $memberIndex, $_ := .Members}}
+    {{  StructMember $struct $memberIndex}}
 {{-   end}}
-} WGPU{{.Name | PascalCase}} WGPU_STRUCTURE_ATTRIBUTE;
+} WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} WGPU_STRUCTURE_ATTRIBUTE;
 {{  end}}{{"\n" -}}
 
 #ifdef __cplusplus
@@ -181,7 +174,7 @@ extern "C" {
 
 {{- range .Functions}}
 {{-   MComment .Doc 0}}
-typedef {{FunctionReturns .}} (*WGPUProc{{.Name | PascalCase}})({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE;
+typedef {{FunctionReturns .}} (*WGPUProc{{.Name | PascalCase}}{{$.ExtSuffix}})({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE;
 {{- end}}
 {{- if eq .Name "webgpu"}}
 typedef WGPUProc (*WGPUProcGetProcAddress)(WGPUDevice device, char const * procName) WGPU_FUNCTION_ATTRIBUTE;
@@ -191,11 +184,11 @@ typedef WGPUProc (*WGPUProcGetProcAddress)(WGPUDevice device, char const * procN
 // Procs of {{$object.Name | PascalCase}}
 {{-   range $object.Methods}}
 {{-     MComment .Doc 0}}
-typedef {{FunctionReturns .}} (*WGPUProc{{$object.Name | PascalCase}}{{.Name | PascalCase}})({{FunctionArgs . $object}}) WGPU_FUNCTION_ATTRIBUTE;
+typedef {{FunctionReturns .}} (*WGPUProc{{$object.Name | PascalCase}}{{.Name | PascalCase}}{{$.ExtSuffix}})({{FunctionArgs . $object}}) WGPU_FUNCTION_ATTRIBUTE;
 {{-   end}}
-{{-   if not .IsStruct}}
-typedef void (*WGPUProc{{.Name | PascalCase}}Reference)(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
-typedef void (*WGPUProc{{.Name | PascalCase}}Release)(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
+{{-   if not (or .IsStruct .Extended)}}
+typedef void (*WGPUProc{{.Name | PascalCase}}Reference{{$.ExtSuffix}})(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
+typedef void (*WGPUProc{{.Name | PascalCase}}Release{{$.ExtSuffix}})(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
 {{-   end}}
 {{  end}}{{"\n" -}}
 
@@ -205,7 +198,7 @@ typedef void (*WGPUProc{{.Name | PascalCase}}Release)(WGPU{{.Name | PascalCase}}
 
 {{- range .Functions}}
 {{-   MComment .Doc 0}}
-WGPU_EXPORT {{FunctionReturns .}} wgpu{{.Name | PascalCase}}({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE;
+WGPU_EXPORT {{FunctionReturns .}} wgpu{{.Name | PascalCase}}{{$.ExtSuffix}}({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE;
 {{- end}}
 {{- if eq .Name "webgpu"}}
 WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUDevice device, char const * procName) WGPU_FUNCTION_ATTRIBUTE;
@@ -215,11 +208,11 @@ WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUDevice device, char const * procName
 // Methods of {{$object.Name | PascalCase}}
 {{-   range $object.Methods}}
 {{-     MComment .Doc 0}}
-WGPU_EXPORT {{FunctionReturns .}} wgpu{{$object.Name | PascalCase}}{{.Name | PascalCase}}({{FunctionArgs . $object}}) WGPU_FUNCTION_ATTRIBUTE;
+WGPU_EXPORT {{FunctionReturns .}} wgpu{{$object.Name | PascalCase}}{{.Name | PascalCase}}{{$.ExtSuffix}}({{FunctionArgs . $object}}) WGPU_FUNCTION_ATTRIBUTE;
 {{-   end}}
-{{-   if not .IsStruct}}
-WGPU_EXPORT void wgpu{{.Name | PascalCase}}Reference(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
-WGPU_EXPORT void wgpu{{.Name | PascalCase}}Release(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
+{{-   if not (or .IsStruct .Extended)}}
+WGPU_EXPORT void wgpu{{.Name | PascalCase}}Reference{{$.ExtSuffix}}(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
+WGPU_EXPORT void wgpu{{.Name | PascalCase}}Release{{$.ExtSuffix}}(WGPU{{.Name | PascalCase}} {{.Name | CamelCase}}) WGPU_FUNCTION_ATTRIBUTE;
 {{-   end}}
 {{  end}}{{"\n" -}}
 
@@ -229,4 +222,4 @@ WGPU_EXPORT void wgpu{{.Name | PascalCase}}Release(WGPU{{.Name | PascalCase}} {{
 } // extern "C"
 #endif
 
-#endif // {{.Name | ConstantCase}}_H_
+#endif // {{.HeaderName | ConstantCase}}_H_