Docs: Extensions #482
Docs: Extensions #482
Conversation
doc/articles/Extensions.md
Outdated
| | | Prefix | Enum Block | Description | ||
| |--------------------|--------------|---------------|------------ | ||
| | Core | (none) | `0x0000_????` | Extensions that are required to implement (e.g. added after 1.0). | ||
| | Multi-Vendor | (none) | `0x0001_????` | Extensions that are optional to implement (e.g. platform-specific extensions). *TBD if enum values in this block may become required, or if they would be aliased into block `0x0000_????` first.* |
There was a problem hiding this comment.
There is a question buried here which I noticed in #417 and then completely forgot about.
Should the new enums really use block 0x0001? Seems like if we ever put this stuff in "core" they could use the same enums, would we then duplicate them into block 0x0000 or just use the block 0x0001 values? Or should we just put them in block 0x0000 to start?
Ugh. Can't keep track of all this minutiae.
There was a problem hiding this comment.
@cwfitzgerald any thoughts? (no rush, I'm ~out until Jan)
There was a problem hiding this comment.
Maybe stupid question... but would it be possible to just renumber an enum if it gets promoted? Would that be a breaking change? (I guess it COULD be if someone is using the actual value of the enum or if we have different header versions in a wire situation?) I'm just wondering how much breakage it could cause and whether we could just promote them and say here that we may do that so don't rely on the actual value of the enums.
There was a problem hiding this comment.
We could say that the value is not API stable, but for ABI stability, we can't just renumber. We can do it if we reserve and implement both the old and new numbers (even though only one is in any given version of the header) but that's kinda obtuse.
There was a problem hiding this comment.
Ok makes sense! Though honestly, the more than one number thing doesn't sound TOO bad IMO.
There was a problem hiding this comment.
I guess the problem here is lack of prefixing. If it were WGPUSType_DawnNewThing = 0x0005_0004 we could easily duplicate it as WGPUSType_NewThing = 0x0000_00A3. But since these are unprefixed we can't duplicate, we can only renumber. But the implementation still needs to handle old numbers that now have no name. We could give them a name with something like:
WGPUSType_NewThing = 0x0001_0004
->
WGPUSType_NewThing = 0x0000_00A3
WGPUSType_OldNameForNewThing = 0x0001_0004
... but I think that's worse than the other two options:
- Give optional extensions a prefix (like
Ext) and remove it when making core (which has a questionable benefit of being able to change the behavior when making it core, though I would avoid doing that) - Merge blocks 0 and 1 and just use documentation to indicate which things are required and which are not
There was a problem hiding this comment.
^ ... or what would happen by default if we didn't change anything:
- Keep blocks 0 and 1 but with the possibility that some things in block 1 end up being required. This is honestly fine and I think we can just go with it.
Actually thinking about the scenario in which this actually happens, it would have to be a multi-vendor extension (meaning we standardized it) which we initially thought would be optional but later became required. I think the most likely case of this is something that's multi-vendor, but we're not sure it's going to show up in the JS API, and then it does. (Like, if the JS API got SPIR-V support somehow, or we decided it was critical to polyfill, then WGPUShaderSourceSPIRV could become required.)
doc/articles/Extensions.md
Outdated
| | | Prefix | Enum Block | Description | ||
| |--------------------|--------------|---------------|------------ | ||
| | Core | (none) | `0x0000_????` | Extensions that are required to implement (e.g. added after 1.0). | ||
| | Multi-Vendor | (none) | `0x0001_????` | Extensions that are optional to implement (e.g. platform-specific extensions). *TBD if enum values in this block may become required, or if they would be aliased into block `0x0000_????` first.* |
There was a problem hiding this comment.
Maybe stupid question... but would it be possible to just renumber an enum if it gets promoted? Would that be a breaking change? (I guess it COULD be if someone is using the actual value of the enum or if we have different header versions in a wire situation?) I'm just wondering how much breakage it could cause and whether we could just promote them and say here that we may do that so don't rely on the actual value of the enums.
Issue: #214