From 76cf8c7d79de4cab04775057c9e788c44d5fed82 Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Fri, 10 Jan 2025 17:59:17 -0800 Subject: [PATCH] Require use of the bitflag registry; improve bitflag docs --- doc/articles/Extensions.md | 8 +-- gen/cheader.tmpl | 4 +- gen/gen.go | 38 +++++++++---- webgpu.h | 107 ++++++++++++++++++++++++++++++++++++- 4 files changed, 140 insertions(+), 17 deletions(-) diff --git a/doc/articles/Extensions.md b/doc/articles/Extensions.md index 355e8f2..20e3879 100644 --- a/doc/articles/Extensions.md +++ b/doc/articles/Extensions.md @@ -61,11 +61,13 @@ Implementation-specific and multi-implementation extensions **must** not use blo | Emscripten | `Emscripten` | `0x0004_????` | | Dawn | `Dawn` | `0x0005_????` | -## 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!) diff --git a/gen/cheader.tmpl b/gen/cheader.tmpl index 387b425..f7cce07 100644 --- a/gen/cheader.tmpl +++ b/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}} diff --git a/gen/gen.go b/gen/gen.go index 773f4a8..fad4640 100644 --- a/gen/gen.go +++ b/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,7 +456,7 @@ func (g *Generator) BitflagValue(b Bitflag, entryIndex int) (string, error) { entryComment += " | " } } - entryComment += " */" + entryComment += "`)" } else { var err error value, err = bitflagEntryValue(entry, entryIndex) @@ -451,8 +464,11 @@ func (g *Generator) BitflagValue(b Bitflag, entryIndex int) (string, error) { 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 { diff --git a/webgpu.h b/webgpu.h index 3637479..97e54c0 100644 --- a/webgpu.h +++ b/webgpu.h @@ -1155,44 +1155,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;