INIT macro follow-up tasks

[kainino0x]

Follow-ups collected from PR #422 (issue #158).

Checkbox = fixed or at least has a PR or issue about it.

• Fix default for buffer binding type #445
• (EDIT: big one so I added it at the top) Proposal: enums in INIT macros always use Undefined #446
  Maybe INIT macros should prefer Undefined over trivial defaults (e.g. /*.dimension=*/WGPUTextureDimension_2D), in case the JS API changes them from trivial (WebIDL) defaults to non-trivial defaults (non-breakingly for JS, in such a way that they depend on the values of other new members or something, but that would make the INIT macros differ slightly).
  (I am not sure if we ever discussed this before. I know we said that we should implement all of WebIDL's trivial defaulting in webgpu.h implementations though.)
  • Affects Proposal: remove Undefined from VertexStepMode and binding type enums #424
• Are we happy with #define WGPU_DEPTH_CLEAR_VALUE_UNDEFINED (NAN) (requires including math.h). Note the JS API disallows NaN (and Infinity) at the WebIDL level
  • We should document the sentinel (any isnan() value I think, but maybe it should be !isfinite() or maybe we should disallow infinities as a validation rule, or clamp them to large finite numbers).
    depthClearValue is undefined iff NaN #467
    Behavior of NaNs and Infinities passed as float/double #466
• Make sure we have the default we want for WGPUCallbackMode (I can't remember if we wanted to default it or not. Does it even matter since people are probably usually going to use these inline anyway? Maybe they don't need INIT macros?)
  Default *CallbackInfo.mode to zero (invalid) instead of WaitAnyOnly #471
• Should we have INIT macros for output-only structs? (like WGPUAdapterInfo)
  • Maybe we can guarantee these are all zero-init?
• Should we have INIT macros when they are equivalent to zero-init, and therefore not really necessary? (see also Abbreviate all-zero INIT macros as {0}? #423)
  • Could be auto-detected or just explicit in the YAML
• Should we name all of the enums' zero values so that the INIT values can be more self-documenting (instead of using _wgpu_ENUM_ZERO_INIT() or whatever)?
  • (we also initialize booleans to 0 but there isn't really a better option for those)
• "Defaults to" sounds kind of like the defaulting occurs inside the API. This is not always true (though it is true for some fields). What we are actually documenting is what the value of the field is when you use the INIT macro.
  Clarify "Defaults to" generated doc #436
• Make sure INIT macros are properly postfixed when defining extension (see Fix inconsistent management of ExtSuffix in INIT macros #453)

[eliemichel]

Should we have INIT macros for output-only structs? (like WGPUAdapterInfo)

Is there a way to know if a struct is output only in webgpu.yml

[kainino0x]

I don't think so, but we can add it.

[kainino0x]

• Maybe INIT macros should prefer Undefined over trivial defaults (e.g. /*.dimension=*/WGPUTextureDimension_2D), in case the JS API changes them from trivial (WebIDL) defaults to non-trivial defaults (non-breakingly for JS, in such a way that they depend on the values of other new members or something, but that would make the INIT macros differ slightly).
  (I am not sure if we ever discussed this before. I know we said that we should implement all of WebIDL's trivial defaulting in webgpu.h implementations though.)

Apparently I did figure this one out, 2.5 years ago. gpuweb/gpuweb#2864 (comment)

[eliemichel]

Another missing point (I think):

• Make sure INIT macros are properly postfixed when defining extension (see Fix inconsistent management of ExtSuffix in INIT macros #453)

[kainino0x]

[ ] Are we happy with #define WGPU_DEPTH_CLEAR_VALUE_UNDEFINED (NAN) (requires including math.h). Note the JS API disallows NaN (and Infinity) at the WebIDL level

Dec 9 meeting:

• Are we happy with #define WGPU_DEPTH_CLEAR_VALUE_UNDEFINED (NAN) (requires including math.h)
• all: OK.
• sentinel is isnan() == true
• Maybe try 0.0/0.0 (hex float is C99, but C++17), otherwise math.h is fine.

• We should document the sentinel (any isnan() value I think, but maybe it should be !isfinite() or maybe we should disallow infinities as a validation rule, or clamp them to large finite numbers)

(I forgot to suggest !isfinite() but it probably doesn't matter. cc @cwfitzgerald just in case you have thoughts)

[kainino0x]

• Maybe try 0.0/0.0 (hex float is C99, but C++17), otherwise math.h is fine.

Does not work in MSVC (#461) so keeping math.h.

[kainino0x]

Dec 12 meeting:

• Should we have INIT macros for output-only structs? (like WGPUAdapterInfo)
• CF: Wouldn't you zero-init these in practice?
  • KN: Or not bother to init.
  • LK: Might be better to init, otherwise if nothing else ends up overwriting it [e.g. there's an error], and you call FreeMembers, it will free garbage pointers.
  • Keep as an indicator that these should be initialized, and for consistency.
• Should we have INIT macros when they are equivalent to zero-init, and therefore not really necessary? (see also "Abbreviate all-zero INIT macros as {0}? #423")
  • Keep for same reason
  • CF: Think we should not abbreviate. They're a form of documentation.
• Should we name all of the enums' zero values so that the INIT values can be more self-documenting (instead of using _wgpu_ENUM_ZERO_INIT())?
  • KN: Removed because there was no use for them. But now we have a place to use them.
  • LK: Maybe annoying for switches because they'll have to name Undefined in order to write exhaustive switches.
  • KN: But also none of our enums are exhaustive even if we do name Undefined.
  • KN/LK: Users still don't really need to name these.
  • CF: It is acknowledged that all enums have zero values, just not named?
  • KN: Yes
  • LK: Defined behavior in all cases? Need to document that?
  • Don't add them back now, can always add back later if we need.
  • Need to make sure that there's no cases where we need to have UB when using unnamed enum values (not just 0, all invalid values) and then document that it's always a validation error.

[kainino0x]

Dec 19 meeting:

• (Assuming we are keeping the INIT macros, since we decided to do that for other structs.)
• > Make sure we have the default we want for WGPUCallbackMode (I can't remember if we ever said whether wanted to default it or not)
• LK: Think it should be 0 (undefined, invalid). If there were a default think it should be Spontaneous. Defaulting to WaitAnyOnly is unergonomic.
• KN: WaitAnyOnly is the most basic option though.
• LK: But then if you don't specify the callback mode, it'll by default never get called.
• KN: Good reason.
• LK: We could change the default later from Undefined to Spontaneous, if we want (should be non breaking).
• Default to Undefined

[kainino0x]

Opened #471. Nothing left to track here so I'm closing this bug.