Add support for polygon clipping

[j9liu]

Fixes #360 #64. Depends on #405 (which itself depends on material keys), so merge that first.

This PR adds support for rasterized polygon clipping.

DISCLAIMER: This requires the Splines package, which is only available in Unity 2022.2 or later. It's not listed as a package dependency, so our package will still load in 2021.3. However, this functionality will be inaccessible in the older versions.

Workflow

The workflow is similar to Cesium for Unreal's. Users can add a CesiumCartographicPolygon from the quick add panel.

This will spawn a game object with a CesiumCartographicPolygon component, which automatically adds a Spline and CesiumGlobeAnchor component. You can modify the game object's transform, add or remove points from the spline component, and edit the spline itself by clicking this icon in the Scene View.

Note that the spline is required to be closed, and completely linear. If either of these conditions is not true, the polygon will log errors. Interestingly, the Spline component supports multiple splines. For simplicity, only the first one is rasterized.

Then, you can connect this polygon to a tileset using the CesiumPolygonRasterOverlay component. The settings are exactly the same as in Unreal.

The materials have been modified to handle alpha clipping via "Clipping" overlay parameters. The final result:

Normal	Inverted Selection

Splines package missing (Unity 2022.2+)

The assembly definition has been modified to reference the com.unity.splines package. If it isn't detected, then the SUPPORTS_SPLINES won't be defined. Users will still be able to add CesiumCartographicPolygon and CesiumPolygonRasterOverlay through the UI, but they will appear with these warnings:

Splines package unavailable (Unity 2021.3f)

com.unity.splines is not listed package.json as a dependency, so Cesium for Unity isn't blocked from loading in earlier versions. When it does load, there will be no UI to add CesiumCartographicPolygon, and CesiumPolygonRasterOverlay is hidden from the component menu. If somehow they make their way into the scene, these warnings will appear:

[j9liu]

Annoyingly, when you first add the overlay, its material key will be initialized with the default value in CesiumRasterOverlay. Reset happens after OnEnable, so it will potentially log a warning that it shares a material key with another overlay on the tileset.

I'll see if I can try doing something similar to CesiumSubScene for circumventing this.

[kring]

In Unity 2022.3 (20f1, but it probably doesn't matter), with the Splines package not installed to start:

1. Add a Cesium Cartographic Polygon using the Cesium panel. A message appears in the log and on the component informing of the need to install the Splines package:

2. Use the Package Manager to install the Splines package.
3. Click on the previously-created CesiumCartographicPolygon. It only has the Cesium Cartographic Polygon component, and there are no controls on it at all:

I tried clicking on a different game object and then back on the CesiumCartographicPolygon game object, but it didn't help. I also tried disabling and re-enabling the Cesium Cartographic Polygon component by clicking the checkbox next to it, but that didn't help either.

Eventually I disabled the entire CesiumCartographicPolygon game object by clicking the checkbox at the top of the inspector.

All the extra stuff immediately appeared, even without enabling it:

Not sure if this is solvable, so it might just be a documentation matter.

[kring]

Also, the created Spline Container in the above scenario had default settings, which made it hard to use.

[kring]

This looks really good! One thing I want to test is that the packaged version of the plugin works just as well, in both 2021.3 and 2022.2. But to do that, we need a working build from CI, which is proving elusive. At the moment, the problem is that Chocolatey is down, so none of our self-hosted builds can start. 😞

[j9liu]

Thanks for the review @kring ! I just pushed some code that should improve the case where a polygon is created before the Splines package is added.

[kring]

I just pushed some code that should improve the case where a polygon is created before the Splines package is added.

I tried this out and it looks good!

I also tested the release package in 2021.3 and 2022.3, and it also works well in both cases.

It's pretty amazing how well this turned out, and how quickly. Nice job!