Add splitDirection property for PointPrimitive and Billboards

[YunVlad]

Description

Add the splitDirection property for PointPrimitive and Billboards.
Objects for which splitDirection is set as SplitDirection.NONE (by default) will be displayed to the right and left of Scene.splitPosition.
Objects for which splitDirection is set as SplitDirection.LEFT will be displayed to the left of Scene.splitPosition.
Objects for which splitDirection is set as SplitDirection.RIGHT will be displayed to the right of Scene.splitPosition.

This property is necessary for marking points of interest and subsequent analysis of changes over time.

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 update the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

[github-actions]

Thank you for the pull request, @YunVlad!

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

[ggetz]

Awesome, thanks for the contribution @YunVlad! We'll review this shortly!

[ggetz]

Awesome @YunVlad!

It would be great to include sample code for this in a Sandcastle example. Would you be open to either adding a new example, or extending an existing example such as this one to showcase this feature?

[ggetz]

Could you please

• merge in the main branch and resolve any conflicts
• Add a link to this PR, ie [11982](https://github.com/CesiumGS/cesium/pull/11982)

[YunVlad]

It was done.
I also added an example in Sandcastle.

[ggetz]

To save on the number of attributes, which is limited, let's pack this single float component along with distanceDisplayConditionAndDisableDepth as a 4th component.

[YunVlad]

Thank you for the comment.
Fixed, added splitDirection as the 4th component in distanceDisplayConditionAndDisableDepth.

[ggetz]

Thanks for the updates @YunVlad!

I noticed one bug during my testing:

When adding a point with viewer.entities.add, setting heightReference to HeightReference.CLAMP_TO_GROUND causes the split property to stop working. Here's a local Sandcastle example demonstrating the issue.

[YunVlad]

I found out why the bug occurs. Until the heightReference parameter is applied, points are rendered by PointPrimitiveCollection shaders (and splitDirection works as intended). However, after applying heightReference, another shader is clearly responsible for rendering (and, unfortunately, it does not work with splitDirection). But I can't figure out which one. Could you help with this question?

I would also like to note that PointPrimitive does not have a heightReference parameter.

[ggetz]

However, after applying heightReference, another shader is clearly responsible for rendering (and, unfortunately, it does not work with splitDirection). But I can't figure out which one. Could you help with this question?

When clamped to ground, points are then represented by billboards rater than Point Primitives. I believe for this to work with the Entity API, you'll also need to implement splitDirection for billboard primitives, namely in BillboardCollectionFS.glsl.

[YunVlad]

Added the splitDirection property for Billboards. Completely by analogy with the one proposed above for Points.
Updated shaders, tests, and also updated the example for Sandcastle.

The bug specified in the local example no longer occurs.

[ilyaly]

Hi there, is there any chance this PR will be merged anytime soon? This feature looks really cool!

[ggetz]

Thanks @YunVlad! Apologies for the delay! This code is looking good. I'm going to go ahead and push a few small updates to make this feature ready for the next release.