Merge branch 'main' into waitstatus-error

doc/articles/Extensions.md

@@ -58,17 +58,19 @@ If an implementation does not have an assigned prefix and block, it **should** b
 |----------------------|--------------|---------------|------------
 | Standard             | (none)       | `0x0000_????` | Extensions standardized in webgpu.h
 | Compatibility Mode   | *TBD*        | `0x0002_????` | **Special:** implementations that don't support Compatibility Mode must ignore any chained structs with @ref WGPUSType values in this block, instead of erroring. This block must only be used for Compat additions that can be ignored without affecting the semantics of a non-erroring program.
-| wgpu-native          | `Wgpu`       | `0x0003_????` |
-| Emscripten           | `Emscripten` | `0x0004_????` |
-| Dawn                 | `Dawn`       | `0x0005_????` |
+| wgpu-native          | `Wgpu`       | `0x0003_????` | -
+| Emscripten           | `Emscripten` | `0x0004_????` | -
+| Dawn                 | `Dawn`       | `0x0005_????` | -
 
 Note all negative values (values with the most-significant bit set to 1) are reserved for future use.
 
-## Registry of extension bit flag values
+## Bitflag Registry {#BitflagRegistry}
 
-Implementation-specific and multi-implementation extensions **should** (*TBD: **must**?*) register new bit flag values of existing bit flag types here.
+Implementation-specific extensions **must** choose one of the following options when adding new bitflag values:
+- Register their reserved bitflag values in this document.
+- Add a new bitflag type, and use it via an extension struct.
 
 Core and Compatibility Mode bits will always be in the least-significant 53 bits, because the JS API can only represent 53 bits.
-Therefore, extended bit flag values **should** be in the most-significant 11 bits, overflowing into the most-significant end of the least-significant 53 bits if necessary (or avoiding doing so by adding a new bit flag type entirely).
+Therefore, extended bitflag values **should** be in the most-significant 11 bits, overflowing into the most-significant end of the least-significant 53 bits if necessary (or avoiding doing so by adding a new bitflag type entirely).
 
 - (None have been registered yet!)

gen/cheader.tmpl

@@ -222,10 +222,10 @@ typedef enum WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} {
  */
 
 {{- range $bitflag := .Bitflags}}
-{{-   MComment .Doc 0}}
+{{-   MCommentBitflagType .Doc 0}}
 typedef WGPUFlags WGPU{{.Name | PascalCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}};
 {{-   range $entryIndex, $_ := .Entries}}
-{{-     MCommentBitflag .Doc 4 $bitflag $entryIndex }}
+{{-     MCommentBitflagValue .Doc 0 $bitflag $entryIndex }}
 static const WGPU{{$bitflag.Name | PascalCase}} WGPU{{$bitflag.Name | PascalCase}}_{{.Name | PascalCase}}{{if $.ExtSuffix}}_{{$.ExtSuffix}}{{end}} = {{BitflagValue $bitflag $entryIndex}};
 {{-   end}}
 {{  end}}

gen/gen.go

@@ -37,12 +37,23 @@ func (g *Generator) Gen(dst io.Writer) error {
 				value, _ := g.EnumValue(prefix, e, entryIndex)
 				return Comment("`"+value+"`.\n"+strings.TrimSpace(v), CommentTypeMultiLine, indent, true)
 			},
-			"MCommentBitflag": func(v string, indent int, b Bitflag, entryIndex int) string {
-				if v == "" || strings.TrimSpace(v) == "TODO" {
-					return ""
+			"MCommentBitflagType": func(v string, indent int) string {
+				var s string
+				v = strings.TrimSpace(v)
+				if v != "" && v != "TODO" {
+					s += v
+				}
+				s += "\n\nFor reserved non-standard bitflag values, see @ref BitflagRegistry."
+				return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true)
+			},
+			"MCommentBitflagValue": func(v string, indent int, b Bitflag, entryIndex int) string {
+				value, _ := g.BitflagValue(b, entryIndex, true)
+				s := value + ".\n"
+				v = strings.TrimSpace(v)
+				if v != "" && v != "TODO" {
+					s += v
 				}
-				value, _ := g.BitflagValue(b, entryIndex)
-				return Comment("`"+value+"`.\n"+v, CommentTypeMultiLine, indent, true)
+				return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true)
 			},
 			"MCommentFunction": func(fn *Function, indent int) string {
 				var s string
@@ -172,7 +183,9 @@ func (g *Generator) Gen(dst io.Writer) error {
 			"CType":        g.CType,
 			"CValue":       g.CValue,
 			"EnumValue":    g.EnumValue,
-			"BitflagValue": g.BitflagValue,
+			"BitflagValue": func(b Bitflag, entryIndex int) (string, error) {
+				return g.BitflagValue(b, entryIndex, false)
+			},
 			"IsArray": func(typ string) bool {
 				return arrayTypeRegexp.Match([]byte(typ))
 			},
@@ -412,7 +425,7 @@ func bitflagEntryValue(entry BitflagEntry, entryIndex int) (uint64, error) {
 	}
 }
 
-func (g *Generator) BitflagValue(b Bitflag, entryIndex int) (string, error) {
+func (g *Generator) BitflagValue(b Bitflag, entryIndex int, isDocString bool) (string, error) {
 	entry := b.Entries[entryIndex]
 
 	var value uint64
@@ -421,7 +434,7 @@ func (g *Generator) BitflagValue(b Bitflag, entryIndex int) (string, error) {
 		if entry.Value != "" {
 			return "", fmt.Errorf("BitflagValue: found conflicting 'value' and 'value_combination' in '%s'", b.Name)
 		}
-		entryComment += " /* "
+		entryComment += " (`"
 		for valueIndex, v := range entry.ValueCombination {
 			// find the value by searching in b, bitwise-OR it into the result
 			for searchIndex, search := range b.Entries {
@@ -443,16 +456,19 @@ func (g *Generator) BitflagValue(b Bitflag, entryIndex int) (string, error) {
 				entryComment += " | "
 			}
 		}
-		entryComment += " */"
+		entryComment += "`)"
 	} else {
 		var err error
 		value, err = bitflagEntryValue(entry, entryIndex)
 		if err != nil {
 			return "", nil
 		}
 	}
-	entryValue := fmt.Sprintf("0x%.16X", value) + entryComment
-	return entryValue, nil
+	if isDocString {
+		return fmt.Sprintf("`0x%.16X`%s", value, entryComment), nil
+	} else {
+		return fmt.Sprintf("0x%.16X", value), nil
+	}
 }
 
 func (g *Generator) TypeSuffixForNamespace(namespace string) string {

webgpu.h

@@ -1146,44 +1146,149 @@ typedef enum WGPUWaitStatus {
  *
  * @{
  */
+/**
+ * For reserved non-standard bitflag values, see @ref BitflagRegistry.
+ */
 typedef WGPUFlags WGPUBufferUsage;
+/**
+ * `0x0000000000000000`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_None = 0x0000000000000000;
+/**
+ * `0x0000000000000001`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_MapRead = 0x0000000000000001;
+/**
+ * `0x0000000000000002`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_MapWrite = 0x0000000000000002;
+/**
+ * `0x0000000000000004`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_CopySrc = 0x0000000000000004;
+/**
+ * `0x0000000000000008`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_CopyDst = 0x0000000000000008;
+/**
+ * `0x0000000000000010`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Index = 0x0000000000000010;
+/**
+ * `0x0000000000000020`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Vertex = 0x0000000000000020;
+/**
+ * `0x0000000000000040`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Uniform = 0x0000000000000040;
+/**
+ * `0x0000000000000080`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Storage = 0x0000000000000080;
+/**
+ * `0x0000000000000100`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Indirect = 0x0000000000000100;
+/**
+ * `0x0000000000000200`.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_QueryResolve = 0x0000000000000200;
 
+/**
+ * For reserved non-standard bitflag values, see @ref BitflagRegistry.
+ */
 typedef WGPUFlags WGPUColorWriteMask;
+/**
+ * `0x0000000000000000`.
+ */
 static const WGPUColorWriteMask WGPUColorWriteMask_None = 0x0000000000000000;
+/**
+ * `0x0000000000000001`.
+ */
 static const WGPUColorWriteMask WGPUColorWriteMask_Red = 0x0000000000000001;
+/**
+ * `0x0000000000000002`.
+ */
 static const WGPUColorWriteMask WGPUColorWriteMask_Green = 0x0000000000000002;
+/**
+ * `0x0000000000000004`.
+ */
 static const WGPUColorWriteMask WGPUColorWriteMask_Blue = 0x0000000000000004;
+/**
+ * `0x0000000000000008`.
+ */
 static const WGPUColorWriteMask WGPUColorWriteMask_Alpha = 0x0000000000000008;
-static const WGPUColorWriteMask WGPUColorWriteMask_All = 0x000000000000000F /* Red | Green | Blue | Alpha */;
+/**
+ * `0x000000000000000F` (`Red | Green | Blue | Alpha`).
+ */
+static const WGPUColorWriteMask WGPUColorWriteMask_All = 0x000000000000000F;
 
+/**
+ * For reserved non-standard bitflag values, see @ref BitflagRegistry.
+ */
 typedef WGPUFlags WGPUMapMode;
+/**
+ * `0x0000000000000000`.
+ */
 static const WGPUMapMode WGPUMapMode_None = 0x0000000000000000;
+/**
+ * `0x0000000000000001`.
+ */
 static const WGPUMapMode WGPUMapMode_Read = 0x0000000000000001;
+/**
+ * `0x0000000000000002`.
+ */
 static const WGPUMapMode WGPUMapMode_Write = 0x0000000000000002;
 
+/**
+ * For reserved non-standard bitflag values, see @ref BitflagRegistry.
+ */
 typedef WGPUFlags WGPUShaderStage;
+/**
+ * `0x0000000000000000`.
+ */
 static const WGPUShaderStage WGPUShaderStage_None = 0x0000000000000000;
+/**
+ * `0x0000000000000001`.
+ */
 static const WGPUShaderStage WGPUShaderStage_Vertex = 0x0000000000000001;
+/**
+ * `0x0000000000000002`.
+ */
 static const WGPUShaderStage WGPUShaderStage_Fragment = 0x0000000000000002;
+/**
+ * `0x0000000000000004`.
+ */
 static const WGPUShaderStage WGPUShaderStage_Compute = 0x0000000000000004;
 
+/**
+ * For reserved non-standard bitflag values, see @ref BitflagRegistry.
+ */
 typedef WGPUFlags WGPUTextureUsage;
+/**
+ * `0x0000000000000000`.
+ */
 static const WGPUTextureUsage WGPUTextureUsage_None = 0x0000000000000000;
+/**
+ * `0x0000000000000001`.
+ */
 static const WGPUTextureUsage WGPUTextureUsage_CopySrc = 0x0000000000000001;
+/**
+ * `0x0000000000000002`.
+ */
 static const WGPUTextureUsage WGPUTextureUsage_CopyDst = 0x0000000000000002;
+/**
+ * `0x0000000000000004`.
+ */
 static const WGPUTextureUsage WGPUTextureUsage_TextureBinding = 0x0000000000000004;
+/**
+ * `0x0000000000000008`.
+ */
 static const WGPUTextureUsage WGPUTextureUsage_StorageBinding = 0x0000000000000008;
+/**
+ * `0x0000000000000010`.
+ */
 static const WGPUTextureUsage WGPUTextureUsage_RenderAttachment = 0x0000000000000010;