chore(core) new device props api

[chrisgervang]

For visgl/deck.gl#8945

Background

DeviceProps API Changes:

For both devices,

• Nest device specific props.
• Allow setting more default canvas context props when creating a device.

For webgl,

• remove onContextLost. Use device.lost instead.
• remove onContextRestore. Luma 9 doesn't support restoring context.

For WebGPU,

• Allow setting more default canvas context props when creating a WebGPU device.

Taking a stab at documenting device props per device and type hinting CreateDeviceProps. Feel free to make corrections or clarifications around the intent behind some of these props, when I was unsure I went off of how the current implementation is written (even though knowing it may be incomplete)

I think deck should use CreateDeviceProps, so I've exported that as well.

Change List

• types
• docs

[chrisgervang]

This is intended to be WebGPU only? It isn't used by WebGL

[chrisgervang]

I've based these defaults on what the docs say. I'm not sure what desynchronized should be by default since the doc was incomplete

[ibgreen]

Not quite convinced that this is worth the extra complexity in term of types etc, compared to just adding two WebGL/WebGPU columns to the DeviceProps docs table.

Also seems to limit the ability to specify WebGL/WebGPU options when using best-available (though I assume that is fixable).

[ibgreen]

What are these changes? Some editor auto correct?

[chrisgervang]

This calls the users onContextLost, if provided

[ibgreen]

This calls the users onContextLost, if provided

I see. Adding a one line bug fix in to a bigger API change is a bit risky, can slip through the review, and can get lost if API change is not approved...

[chrisgervang]

Happy to split this out. I didn't mean to put anything risky in here. The reason I included this is get clarity on the intended API. It's unclear to me what the intent is.

If users shouldn't be able to provide onContextLost by design, then the API types need to be adjusted a bit. If we can agree the user should be able to provide onContextLost, then this is a bug and I'll pull that into another PR.

[ibgreen]

Now that you shine a light on it, I think we should completely drop support for onContextLost. Such callback code tends to be surprisingly messy to keep working across devices and it doesn't add value.

We don't talk about contexts anymore, just devices. and we have the replacement in the WebGPU style promise API: device.lost

App can register its onContextLost callback with device.lost.then(onContextLost).

[chrisgervang]

I agree. device.lost sounds better since it the same API for both devices, making this redundant.

Is there a device equivalent for onContextRestore as well?

[ibgreen]

No, context restore is not supported by luma.gl v9.

The problems is that properly handling context restore in non-trivial apps is very tricky, since all resources are lost and have to be recreated, and the data that was used to create buffers and textures may not have been saved.

\Showing a message asking the user to just refresh the page is usually best way out.

WebGPU doesn't support restore.

[chrisgervang]

Should the onContextRestore code in the WebGL device be removed then?

[ibgreen]

Yes. I would vote for that. It is not impossible for an app to register the callback even if luma.gl API doesn't support it, they will just need to get the context and add an event handler themselves.

[chrisgervang]

The vision here makes sense to me, that one day we’ll be able to use best-available and luma will match the default behaviors between the devices as best as it can. However, I still believe there’s a need for discriminated union types.

The complex typing reflects a complex API; deviceProps are effectively two different objects (or the union of those) depending on their use case, and then another union with additional properties for createDevice. These APIs are challenging to explain, but types can help.

I think these types should be as helpful to users as possible. It defeats the purpose if users need to constantly refer to the documentation just to know which properties they can use, especially when they are explicitly using WebGL or WebGPU.

I think the goal should be to provide clarity and reduce the cognitive load, and I'm open simpler implementations if they exist.

[ibgreen]

The vision here makes sense to me, that one day we’ll be able to use best-available and luma will match the default behaviors between the devices as best as it can. However, I still believe there’s a need for discriminated union types.

The complex typing reflects a complex API; deviceProps are effectively two different objects (or the union of those) depending on their use case, and then another union with additional properties for createDevice. These APIs are challenging to explain, but types can help.

I think these types should be as helpful to users as possible. It defeats the purpose if users need to constantly refer to the documentation just to know which properties they can use, especially when they are explicitly using WebGL or WebGPU.

I think the goal should be to provide clarity and reduce the cognitive load, and I'm open simpler implementations if they exist.

In loaders.gl we have options sub-objects for each loader, the same model could work here:

luma.createDevice({
 // common options
 webgl: {
   // webgl specific options,
 },
 webgpu: {
   // webgpu specific options
 }
};

It would be slightly breaking but make it very clear what is going on.