Tiles: options enhancements

[Avnerus]

Updated options for tiles.
Here is the snippet from the revised documentation:

• options.viewDistanceScale=1.0 (Number) - A scaling factor for tile refinement. A lower value would cause lower level tiles to load. Useful for debugging and for restricting resource usage.
• options.updateTransforms=true (Boolean) - Always check if the tileset modelMatrix was updated. Set to false to improve performance when the tileset remains stationary in the scene.
• options.loadOptions - loaders.gl options used when loading tiles from the tiling server. Includes fetch options such as authentication headers, worker options such as maxConcurrency, and options to other loaders such as 3d-tiles, gltf, and draco.
• options.contentLoader = null (Promise) - An optional external async content loader for the tile. Once the promise resolves, a tile is regarded as READY to be displayed on the viewport.

Also fixed some missing examples in the website and upgraded dependencies.

[ibgreen]

@Avnerus can you rebase this PR?
@belom88 Can you help @Avnerus land this PR?

[Avnerus]

Now rebased

[ibgreen]

Should we make a breaking change and drop the headers option as it is now covered by loadOptions.fetch? This class is really complex, with so many options. Could certainly be a separate PR.

[Avnerus]

That is fine by me!

[ibgreen]

OK I created an API cleanup section here: #1245 where we can track proposals for API changes.

[ibgreen]

Since we are about to launch 3.0, a major release we do have a rare opportunity to make breaking changes, so if we have ideas for how to clean up the sprawling Tileset3D API now is a good time.

[ibgreen]

We already have an onTileLoad callback. Do we need to add another callback? If we do, can we follow the convention and call it onTileContentLoad or similar?

[Avnerus]

This is not the same as the onTile* callbacks which are essentially events.
The content loader promise must resolve before a tile can set

      this.contentState = TILE_CONTENT_STATE.READY;
      this._onContentLoaded();

And only then those callbacks may be fired.
Without this solution there is no way to use async loaders such as the three.js GLTFLoader without experiencing a race condition in which a tile is selected before it is actually on the render graph.

[ibgreen]

Understood, thanks for clearing up the use case.

Would it make sense if we could declare it as onTileContentLoad(tile: Tile3D): Promise<void> and we wait for it?

[Avnerus]

I am a bit hesitant because usually on* callbacks are not something you would expect would block execution. But I defer to you on this one.

[ibgreen]

Yes I can see your point. Thoughts:

• contentLoader risk being confusing in a framework that is specifically built around a concept of "loaders". I would have expected an option with that name to accept a loaders.gl loader.
• Perhaps another name, ideally indicating some new naming convention?
• We could also allow all the on... functions to return promises though this might lead to unintended synchronization for current users, if they are using async functions as callbacks.

When working with a big documented API the API audit tends to be a big part of the effort. This is why it is often best to make one PR for every addition, instead of one PR with 4 new props :)

[Avnerus]

Perhaps tileProcessingHook or something of sort?
Understood about the heavy PRs. Will work to make those leaner in the future.

[ibgreen]

We could also supply a requestSchedulerOptions object. It would avoid creating one more mapping of options and the documentation could be unified.

[Avnerus]

But the only relevant request scheduler option is maxRequests.
This line actually slipped in here from the traversal PR which I still need to rebase.