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

[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.

[ibgreen]

OK I have made another pass on this. Decided to go with some technically breaking changes to clean up the API, shouldn't lead to any subtle issues.

• Collected webgl specific props in DeviceProps.webgl
• Collected canvasContext specific props in DeviceProps.canvasContext
• Sets preserveDrawingBuffers to true by default (presumably the reason why this big change was started anyways)

[chrisgervang]

Nice progress! Left a few comments. I'm wondering if we should warn when features that are only WebGL or only WebGPU are used on an incompatible device, like "debug"? When the lib does nothing I can foresee that being a long debugging session to learn what exactly is and isn't supported, specifically for any potentially ambiguous top-level device props. What do you think?

[ibgreen]

Nice progress! Left a few comments. I'm wondering if we should warn when features that are only WebGL or only WebGPU are used on an incompatible device, like "debug"? When the lib does nothing I can foresee that being a long debugging session to learn what exactly is and isn't supported, specifically for any potentially ambiguous top-level device props. What do you think?

• While developer experience is important, there is a real bundle size overhead to sprinkling the code with checks and error messages, which makes me hesitate.
• I cleaned up the options and their naming which should make things much clearer.
• And also added clear TSDoc comments (which should be visible in e,g, vscode when hovering over props) to indicate what is device specific.

[ibgreen]

Have a few test failures, plan to merge when they are sorted.

[chrisgervang]

I like the new names, and the docstrings are very helpful! Thanks for pushing this forward.

[chrisgervang]

Why might someone use this?

It is a tradeoff between reuse/speed and memory. I added it to unblock things until we find the right balance.

[chrisgervang]

Might be good to document the renamed device props and removal of "break" before merging

[ibgreen]

I like the new names, and the docstrings are very helpful! Thanks for pushing this forward.

Great review, you are really paying attention to this! Agree with all your proposals. Would you mind applying your changes? Landing this PR has become a pretty big effort, so teamwork is appreciated.

[ibgreen]

@chrisgervang This is passing CI after lots of iterations. Will land and we can take your suggestions in a follow up PR.