Vector Textures for Polygon Clipping

[mzschwartz5]

Description

This is the second step in reimplementing Clipping Polygons on top of the vector data pipeline. In step one, I created a BufferPolygonCollection as a mirrored backing data structure for the ClippingPolygonCollection class. In this PR, I expose a new (internal) API on ClippingPolygonCollection -- requestRectangleData -- analogous to the similarly named versions provided by VectorProvider. This API accepts a rectangular region of an ellipsoid, and processes the clipping polygons within that rectangle to create textures used for vector-style clipping (by calling the VectorPipeline APIs).

There is also a parallel releaseRectangleData API. The intention is for various consumers (terrain, 3d tiles, standalone models) to call these APIs with their respective footprint rectangles.

Issue number and link

https://github.com/iTwin/cesiumjs-web3d-internal/issues/32

Testing plan

Again, there are no outward facing changes in this PR. At this point, clipping still relies on the SDF path. The machinery is just being put into place for vector clipping. As such, more regression testing suffices (sandcastle)

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

AI acknowledgment

• I used AI to generate content in this PR
• If yes, I have reviewed the AI-generated content before submitting

If yes, I used the following Tools(s) and/or Service(s):

If yes, I used the following Model(s):

PR Dependency Tree

• PR Clipping polygon buffer migration #13623
  • PR Vector Textures for Polygon Clipping #13635 👈
    • PR Clipping texture plumbing #13636
      • PR Shader rework for terrain polygon clipping #13637
        • PR Remove SDF polygon clipping from Globe #13638
          • PR Model clipping rework foundation #13641
            • PR Model polygon clipping shader impl #13647
              • PR Remove polygon clipping sdf path #13654
                • PR Clipping Polygon Holes #13660
                  • PR ClippingPolygon immutable positions (performance) #13665

This tree was auto-generated by Charcoal

[github-actions]

Thank you for the pull request, @mzschwartz5!

✅ We can confirm we have a CLA on file for you.

[danielzhong]

I think there's a staleness issue with refreshing the vector data here. polygonAdded / polygonRemoved fire synchronously inside add() / remove(), but this repack doesn't happen until the next update(). Since the doc on requestRectangleData tells consumers to re request in response to those events, they could end up reading a snapshot that doesn't include the new polygon yet.

Also, because update() early returns when totalPositions hasn't changed, removing one polygon and adding another with the same vertex count never reaches this line at all, the vector data stays stale forever. That's a known trade off of the SDF path, but it silently carries over into the new API.

One more thing: we never pass the third result arg (or call markClean()), so the version short-circuit in packPolygonCollectionData can never kick in, every call is a full repack with fresh allocations.

What do you think about dropping this hook (and the eager pack in the constructor) and refreshing lazily inside requestRectangleData instead? Something like:

this._vectorCollectionData = VectorPipeline.packPolygonCollectionData(
  this._bufferPolygonCollection,
  this.ellipsoid,
  this._vectorCollectionData,
);
this._bufferPolygonCollection.markClean();

[mzschwartz5]

I think there's a staleness issue with refreshing the vector data here.

Good call out. I think this could be reframed as more of a documentation issue, though. The docs should tell readers to listen for add()/remove(), but that the collection data refreshes on the next update(). In up-stack PRs, you can see how consumers mark a flag as dirty when add/remove are called, and then re-request rectangle data on the next update.

(One could alternatively change the code, so that the data repacks lazily in requestRectangleData, and is thus never stale. However, Globe and Models actually call ClippingPolygonCollection.update() manually, so they're already in control of the lifecycle of this vector data resource, if that makes sense. In fact, unlike other entities in Cesium, ClippingPolygonCollection.update is only ever called by its owner, despite what the method's docs say).

Also, because update() early returns when totalPositions hasn't changed, removing one polygon and adding another with the same vertex count never reaches this line at all, the vector data stays stale forever.

This is also true, but it's addressed in a PR later in the stack. Eventually, we remove that check entirely and rely on a plain dirty flag.

One more thing: we never pass the third result arg (or call markClean()), so the version short-circuit in packPolygonCollectionData can never kick in, every call is a full repack with fresh allocations.

I think that's okay. The purpose of the third arg is as a caching optimization -- one that only works if using the version number on the buffer collection. I designed these ClippingPolygonCollection changes to use push-based notifications (the add()/remove() events) instead of pull-based (version numbers), so any caller to requestRectangleData already knows their data is dirty and needs a refresh.

Think of ClippingPolygonCollection as an alternative to VectorProvider. While consumers of VectorProvider call updateTileData each frame and let VectorProvider track caches and dirtiness, consumers of ClippingPolygonCollection subscribe to its dirty events, and use those as signals to rerequest data.