🐛 Bug: Billboard depth test rendering regression compared to 1.132.0 Description

[912807862]

What happened?

When rendering a Billboard with depth testing enabled, the visual result appears incorrect in newer versions of Cesium compared to version 1.132.0.

Specifically, the billboard is not properly occluded by terrain when it should be partially or fully hidden behind it.

Expected Behavior

As shown in Cesium 1.132.0, the billboard should be correctly depth-tested against terrain:

The billboard is properly occluded when behind terrain

Only the visible portion should be rendered

Actual Behavior

In newer versions:

The billboard appears incorrectly rendered

It is either:

Not occluded at all, or

Incorrectly clipped/positioned relative to terrain depth

Screenshots

Correct behavior (Cesium 1.132.0):

Incorrect behavior (newer version):

Reproduction Steps

Create a Billboard positioned near terrain surface (e.g., hillside)

Enable depth testing:

viewer.scene.globe.depthTestAgainstTerrain = true;

Position the camera at an angle where terrain should occlude the billboard

Observe rendering differences between versions

Environment

Cesium version:1.139.0

Additional Notes

This appears to be a regression introduced after 1.132.0

The issue is especially noticeable when the billboard is placed close to terrain slopes

It may be related to depth buffer precision or billboard rendering pipeline changes

Possible Related Settings
billboard.disableDepthTestDistance = 0;

[mzschwartz5]

Hi @912807862 - are you able to provide a simple reproduction in a sandcastle? There have been a lot of changes to billboard depth testing recently, so I'd like to play around with this and test for myself. It's also important to make sure to test on the latest version of Cesium here, if you're not already - each of the last few versions has tweaked depth testing slightly (or majorly, in some cases).

[mzschwartz5]

Based on the images - it also looks like you might be using translucency? That could be a path we didn't test fully.

[912807862]

Thanks for the quick response!
Regarding translucency:
I am indeed using a PNG with transparency (alpha channel), but this is intentional . Even without translucency, the occluded portion of the billboard should not be visible when depth testing works correctly.

While investigating further, I found something interesting that may help narrow this down:

• If I do NOT use CallbackProperty, the depth testing behaves correctly:
  • The billboard is partially occluded by terrain as expected (e.g., half visible, half hidden)
• If I introduce a CallbackProperty before rendering (even a simple one like below), the behavior becomes incorrect:

new Cesium.CallbackProperty(() => {
return someValue;
}, false);

After using CallbackProperty, the billboard no longer behaves correctly with depth testing:
Instead of being partially occluded, it becomes either:
fully visible, or completely hidden
This breaks the expected depth testing behavior against terrain, especially noticeable on slopes.
Also, I am currently testing this on the latest version of Cesium.
So this might be related to how dynamic properties (CallbackProperty) interact with billboard rendering or depth testing.

[mzschwartz5]

That's a helpful detail to narrow things down. Could you perhaps provide a sandcastle that reproduces what you're seeing?

[912807862]

Please refer to the Sandcastle demo I provided.

https://sandcastle.cesium.com/#c=nVTfb9owEP5XLJ7CFBmyaqwFWm2j1fbQlqll7UskZJJLsOrYzHboaMX/vnOcBGinPcBD8P34znffdzIvVkpb8oEwQyZgeFmQTKuCxJ2ksuLOKJbcJ90zmSbMWAFNzs5T5cUyUdJYsubwDJqcEwnPdVX6UPmCpu5EScu4BB13QvIaS0IsaI2eYQOYeZu6qx6VFmntCKpsQjT8LsHYR4bAG2aehiRjwkB4EH0AbeHPrdIFxvYztl3823ZHTcsrZbjlSmLT9f0ThlDDmTypWriEXAOYIIpO6Wl01h+cheTkI+0PBoNPn0MS4XkQ7eqBtNxusJrnglY2B0NZmvoJmhuH7alqbMGFWCim0yGpB+UFy2GIbFPaq86m51ucX6tczdUatGAbupI5cukh6LI8YWKqeb5H6cOBm06ubmdXdzVkqTR/caK8Bf14E9iHbRsSYynAOrmvqrnRU8+dic1MBZ6N8DUtNatm7m+7DrTbH8fLTOW5gG+ltUrioqDHV3Mr4pUjWSmTSqYgWULyBGnXs+RIV1hFqLyNjFyAZ61d09k2+T9x3G8n0HEbEVUbETbl3gt7pLhHCny0yDUUeL60d5CBBpnADnnop5Prrzc/57Pp/Pvd9NftZVthW5+c8PgFlLOl4a0MGgocPGiV8pB61TphZ2zsRsCF836p36ZSiwAptFCsBL4IprcoUXRLE2McaNxrIOOUrwlPz//xEJFEMGMwkpVC3PMXfNQuxj3MP4AJxVIu86lXxqUso4tr76SUjntovkdZpcSC6b2KfwE

Steps to reproduce:

1. After opening the demo, adjust the camera to the specified viewpoint (as shown in the initial view).
2. Enable the addEntity toggle.
   At this point:

• A new billboard is created with the following setting:
  heightReference: Cesium.HeightReference.CLAMP_TO_GROUND
  After this billboard is added, the depth testing behavior of the existing billboard becomes incorrect.

Specifically:

Before enabling addEntity, the original billboard is correctly partially occluded by terrain

After enabling it, the original billboard's depth testing breaks, becoming either fully visible or fully hidden

This suggests that adding a clamped-to-ground billboard may be affecting the depth testing behavior of other billboards in the scene.

The previously mentioned CallbackProperty was part of my earlier investigation, but it is not related to this issue and is not required to reproduce the problem.
This suggests the issue is related to how ground-clamped billboards affect depth testing of other billboards in the scene.

[mzschwartz5]

Hi @912807862 - thanks for the sandcastle demo. I see what's going on here, and while it is intended behavior, it's not made clear enough to users. Basically, clamped billboards have a special behavior - they try to stay entirely visible or entirely hidden when viewed close-up. They avoid partial-occlusion because terrain tends to noisily poke through clamped billboards all over.

When you add the second (clamped) billboard, the first one copies that behavior, even though it's not clamped itself. This is because the setting pertains to the collection of billboards - not to individual billboards. When you add billboards to the scene directly, the scene creates its own collection. When you put the second, clamped billboard in the scene, the scene's collection enables that clamping behavior.

You can work around that by maintaining two separate billboard collections explicitly: one for clamped billboards, one for unclamped. See how I changed your demo here. In the new demo, the old behavior remains for the first billboard, but the second billboard has the special clamped behavior. If you don't like that behavior, you can effectively disable it by setting clampedCollection.threePointDepthTestDistance = 0. See here. (If that's the behavior you want for all billboards, then you only really need a single collection with that value)

Hope that helps. It seems like this may be a different issue than the one you originally identified / the one with callbacks? If so, I'd appreciate it if you could provide a sandcastle for that particular issue, too. If not, I'll close this issue. Thanks!