Skip to content

Require use of the bitflag registry; improve bitflag docs #493

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kainino0x merged 2 commits into from
Jan 17, 2025
Merged

Require use of the bitflag registry; improve bitflag docs #493

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76cf8c7
Require use of the bitflag registry; improve bitflag docs
kainino0x Jan 11, 2025
ee2e067
Merge branch 'main' into bitflag-registry
kainino0x Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions doc/articles/Extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,13 @@ If an implementation does not have an assigned prefix and block, it **should** b

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!)
4 changes: 2 additions & 2 deletions gen/cheader.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}
Expand Down
38 changes: 27 additions & 11 deletions gen/gen.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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))
},
Expand Down Expand Up @@ -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
Expand All @@ -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 {
Expand All @@ -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 {
Expand Down
107 changes: 106 additions & 1 deletion webgpu.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1155,44 +1155,149 @@ typedef enum WGPUWaitStatus {
*
* @{
*/
/**
* For reserved non-standard bitflag values, see @ref BitflagRegistry.
*/
typedef WGPUFlags WGPUBufferUsage;
/**
Copy link
Collaborator

@lokokung lokokung Jan 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit. These all seem really redundant, given that its documented in the code right below. Is it for doc generation that this is necessary?

Copy link
Collaborator Author

@kainino0x kainino0x Jan 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right it's pretty redundant. Turns out the docs do show the definition:
image
unlike for enums:
image

Of course this html view is not the only possible way to look at things. But maybe the only useful docs are special cases like 0 and Red|Green|Blue|Alpha. Will follow up.

* `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;


Expand Down
Loading