Default descriptor initialization (and discussion of C vs C++ callbacks)

[mrshannon]

Many of the descriptors in WebGPU have default values, and more importantly default values which are not 0 and so a simple memset or zero initialization is not appropriate.

An example of what does not work

WGPUTextureDataLayout TextureDataLayout = {0};
TextureDataLayout.bytesPerRow = 512;

In this case rowsPerImage = 0 instead of WGPU_COPY_STRIDE_UNDEFINED.

Therefore, I propose adding default initialization defines to webgpu.h. While it is possible for each user to create their own, there are some benefits to implementing this in webgpu.h:

• Adding fields later with default values to descriptors does not introduce undefined behavior in existing code.
• It is possible to change default values later without breaking existing code (while WGPU_COPY_STRIDE_UNDEFINED fixes this, many defaults do not have a define as they are simply 0).
• One source of truth

One way to implement this is to add defines for each descriptor:

#define WGPUTextureDataLayout_DEFAULT { NULL, 0, WGPU_COPY_STRIDE_UNDEFINED, WGPU_COPY_STRIDE_UNDEFINED }

This would allow users to write:

WGPUTextureDataLayout TextureDataLayout = WGPUTextureDataLayout_DEFAULT;
TextureDataLayout.bytesPerRow = 512;

---

TODO list:

• Don't forget to write compile tests for these! Add tests that instantiate macros #240

[Kangz]

This would have helped us a lot in Chromium at various time when removing / deprecating members :) I could change the generator to produce these defines at the bottom of the webgpu.h (guarded with a #ifndef WGPU_SKIP_STRUCT_DEFAULT_MACROS or something).

Other folks WDYT? In particular @cwfitzgerald @kvark @jimb?

Also @mrshannon, you could use the C++ headers generated by Dawn, they have default initialization for the various structs.

[grovesNL]

This sounds reasonable to me. We use defaults for a lot of types in wgpu and find it really useful, e.g. PrimitiveState https://github.com/gfx-rs/wgpu/blob/77b2c25684f971daa977596403f01c71d32ea685/wgpu/examples/msaa-line/main.rs#L65-L69

[mrshannon]

Also @mrshannon, you could use the C++ headers generated by Dawn, they have default initialization for the various structs.

Sort of off topic, but we were initially using the C++ headers but dropped them for the C headers as we kept having to cast everywhere because the callbacks always use the C types and not the C++ types. But that came with it's own issues (WGPUBufferUsage vs WGPUBufferUsageFlags), maybe it's time to consider switching back.

[Kangz]

Any idea on how to improve WGPUBufferUsage vs. WGPUBufferUsageFlags?

For the C++ header typedefs I'm not sure how to fix it because technically the signatures of the functions are different so if we want UBSan to be happy we would need to make an indirection (and allocation).

[mrshannon]

Any idea on how to improve WGPUBufferUsage vs. WGPUBufferUsageFlags?

You technically don't need WGPUBufferUsageFlags as WGPUBufferUsage will always be wide enough for the bitwise combination because we have WGPUBufferUsage_Force32 = 0x7FFFFFFF which is effectively doing what is done for the C++ headers with:

enum class BufferUsage : uint32_t {

For the C++ header typedefs I'm not sure how to fix it because technically the signatures of the functions are different

Correct, I don't think there is either, not without allocating a std::function on the heap and destroying it later (not a good idea). But what could be done is to make it clear (without looking at implementation files) that the C and C++ enums are safe to cast by providing a casting function. In our engine we do all kinds of seemingly "unsafe" casting but it is behind a type-trait like function which always performs the "safe" cast.

I am also not sure it makes sense to have:

using BufferMapCallback = WGPUBufferMapCallback;

Because without that it's at least clear the callbacks will always be using the C API.

But again, this is way off topic (with relation to the initial issue), so perhaps we should continue this somewhere else?

[kainino0x]

You technically don't need WGPUBufferUsageFlags as WGPUBufferUsage will always be wide enough for the bitwise combination because we have WGPUBufferUsage_Force32 = 0x7FFFFFFF which is effectively doing what is done for the C++ headers with:

EDIT: Actually let me split that out into a separate issue. #159

[kainino0x]

I split the flags discussion out to #159, since it's mostly off-topic.

[Kangz]

@mrshannon we could have a wgpu::FromC(...) and wgpu::ToC(...) serie of functions that convert between the C and C++ datatypes. WDYT?

[mrshannon]

@mrshannon we could have a wgpu::FromC(...) and wgpu::ToC(...) serie of functions that convert between the C and C++ datatypes. WDYT?

I think that's a good idea. Makes it clear without looking at the implementation that those casts are safe.

[kainino0x]

For the C++ header typedefs I'm not sure how to fix it because technically the signatures of the functions are different so if we want UBSan to be happy we would need to make an indirection (and allocation).

This is kind of a dumb idea, but what if the C API had two userdata pointers, and the C++ wrapper used one for the C++ callback? I can imagine this being useful for other language bindings, as well. Would look vaguely like:

namespace wgpu {
    typedef void (*RequestDeviceCallback)(RequestDeviceStatus status, Device device,
            char const * message, void * userdata);

    void RequestDeviceWrapper(WGPURequestDeviceStatus status, WGPUDevice device,
            char const * message, void * userdata, void * binding_userdata) {
        RequestDeviceCallback callback = static_cast<RequestDeviceCallback>(binding_userdata);
        callback(static_cast<RequestDeviceStatus>(status), Device{device}, message, userdata);
    }
    void Adapter::RequestDevice(DeviceDescriptor const * descriptor, RequestDeviceCallback callback,
            void * userdata) const {
        wgpuAdapterRequestDevice(Get(), reinterpret_cast<WGPUDeviceDescriptor const * >(descriptor),
                RequestDeviceWrapper, reinterpret_cast<void * >(userdata), callback);
    }
}

[mrshannon]

Here is an example of WebGPU INIT/NULL defines we use for our project, pulled from our WebGPU utility library. It's not quite the same as the defaults in the C++ API provided by Dawn/Emscripten as it's defaults are based on the JS API and includes NULL initialization (which is required for some of the C structs). But it shows some the reasons why upstreaming this is preferred, differences between implementations which we had to paper over with #ifdef.

[kainino0x]

I'm ever so slightly sad that our default structs aren't just all zeroes. I'm just spitballing - apparently this is the thread where I come up with silly C API ideas - but how awful would it be if instead of sentinel 0xFFFF_FFFF values we had a separate field to specify whether you've set the thing or not? (Basically a "type" field for whether it's undefined or int.)

This would also mean implementations must implement the same defaults that are specified in WebIDL, i.e. turning _Undefined values into their defaults, but I kinda think that is a good idea anyway.

[mrshannon]

apparently this is the thread where I come up with silly C API ideas

I am honored to have started it.

separate field to specify whether you've set the thing or not?

One option for this is for optional numbers the type could be changed to something like:

strict OptionalUint32 {
    bool set;
    uint32_t value;
}

This way you could do:

WGPUTextureViewDescriptor desc = {0};
desc.baseArrayLayer = {true, 4};
desc.arrayLayerCount = {true, 1};

It's interesting, and much more self documenting. But it does add quite a bit of complexity when setting optional numbers.

I think the bigger issue is with the nullable structs which are not NULL at the top but are NULL because something inside them is _Undefined. To me that is the bigger issue as it makes it very hard to understand what is going on. I think I would rather see something similar to blend in WGPUColorTargetState where the sub structure is given by pointer, as that is far more self documenting.