Vector tile geometry is always drawn in the translucent pass, so opaque features do not occlude each other

[danielzhong]

What happened?

Overlapping vector tile features blend through each other instead of occluding, even when the style is fully opaque. This is visible both within a layer and between layers. For example a polygon layer and a polyline layer covering the same area, where the polylines stay visible through the polygons.

createVectorTileBuffersFromModelComponents constructs BufferPointCollection, BufferPolylineCollection, and BufferPolygonCollection without passing blendOption, so they fall back to the BlendOption.TRANSLUCENT default. The renderers map that to Pass.TRANSLUCENT, and OIT.getTranslucentRenderState forces depthMask = false, so no depth is written.

Cesium3DTileStyle alpha never reaches blendOption, so color('red', 1.0) and color('red', 0.3) take the same path.

Reproduction steps

1. Load two vector tilesets covering the same area, one polygons and one polylines.
2. Style both with a fully opaque color, e.g. color('red', 1.0).
3. Orbit the camera. The polylines remain visible through the polygons.
   ...

Sandcastle example

No response

Environment

Browser:
CesiumJS Version:
Operating System:

AI acknowledgment

• I used AI to generate this issue report.
• (If the above is checked) I have reviewed the AI-generated content before submitting.

[donmccurdy]

I wish I understood why Pass.TRANSLUCENT had this effect... it feels like two "translucent" polygons with opacity=1.0 should not blend through each other, regardless of the blendOption ... but they do, and it seems that's not specific to vector collections.

In this PR...

• BufferPrimitiveCollection: Add 'zIndex' option #13515

...I had proposed a possible solution (which could be split into a separate PR needed), awaiting review. I guess I'm wondering whether this ought to be "fixed" for blendOption=TRANSLUCENT too, or if that's intended behavior. If this is the behavior we want for blendOption=TRANSLUCENT then I agree making blendOption mutable would make sense.

[danielzhong]

@donmccurdy @ggetz @arobison @mzschwartz5

it feels like two "translucent" polygons with opacity=1.0 should not blend through each other ... and it seems that's not specific to vector collections.

You're right that it isn't specific to vector collection, anything placed in Pass.TRANSLUCENT behaves this way, including Model and Primitive. The difference is that opaque geometry doesn't normally end up there, so the bug isn't in the behavior of the pass, it's in the classification.

I'm wondering whether this ought to be "fixed" for blendOption=TRANSLUCENT too, or if that's intended behavior.

My take is that it shouldn't be. Your intuition matches BlendingState.ALPHA_BLEND, which is exactly the formula above at α = 1.0 the destination term drops out and the source just replaces what's behind it. But Pass.TRANSLUCENT never uses it: OIT.createDerivedCommands rewrites the render state with rs.depthMask = false; rs.blending = translucentBlending; (OIT.js#L448-L450), replacing whatever blendOption picked with ONE / ONE — pure addition. The (1-α) term is gone, so α becomes a weight in a sum rather than a coverage factor, and two α = 1.0 surfaces average instead of occluding. The semantics of Pass.TRANSLUCENT are "give up depth sorting in exchange for an order-independent approximate blend"; making alpha=1.0 occlude inside it would mean restoring depthMask, which is effectively turning OIT off and would change translucent rendering across all of Cesium.

The actual bug is that opaque content is being misclassified into the translucent pass. That's what your Pass.VECTOR and the style→blendOption change each address from a different angle: one keeps vector primitives out of OIT entirely, the other keeps opaque content from being labeled translucent in the first place.

Since the two overlap, here's what I'd propose:

1. Land BufferPrimitiveCollection: Add 'zIndex' option #13515 first. Pass.VECTOR is the more general fix. It covers all alpha values, not just the fully-opaque case, and zIndex needs it anyway (polygon offset does nothing inside OIT, where depthMask is off). Happy to review it.

2. Trim this PR to just the classification half: a setter for blendOption, plus applyStyle deriving it from the alpha the style evaluates to. Still needed either way, since Pass.VECTOR has to pick between DISABLED and ALPHA_BLEND, and only the style knows which and the style runs after construction, so it can't be a constructor option.

3. blendOption is per-collection, so a mixed style like "${highlight} ? color('yellow', 0.4) : color('gray', 1.0)" forces the whole collection translucent. The VECTOR_OPAQUE / VECTOR_TRANSLUCENT split you mentioned in the PR would address this and allow opaque and translucent features to be handled separately.

One question on #13515: how does Pass.VECTOR handle depthMask and draw order when blendOption=TRANSLUCENT? ALPHA_BLEND with depth writes is order-dependent.

Update: checked the branch: Pass.VECTOR commands keep depthMask at its default true and performPass doesn't sort, so with blendOption=TRANSLUCENT overlapping surfaces depth reject each other by traversal order instead of blending, and zIndex doesn't help since polygon offset shifts depth but not draw order. Is that the VECTOR_TRANSLUCENT case you had in mind?

[donmccurdy]

Thanks! What I was missing when implementing #13515 was not knowing that Pass.TRANSLUCENT behaves this way because of OIT. It's helpful to see that disabling OIT works around the issue...

const viewer = new Cesium.Viewer("cesiumContainer", {
  orderIndependentTranslucency: false,
});

Given that information, vectors might as well behave as other opaque and translucent primitives, and not be excluded from OIT without a compelling reason. So maybe we don't need Pass.VECTOR right now?

I'm not sure whether blendOption should be derived automatically (entire layer is translucent if >=1 primitive is translucent), or left to user configuration on the tileset and/or styleset, but I'd defer to you, @ggetz, and @arobison on that.

I agree we can make blendOption mutable on BufferPrimitiveCollection, if we decide to derive it automatically at the Cesium3DTileset level.

[ggetz]

@danielzhong @donmccurdy IIUC, at the root of the issue, are we looking at a manifestation of #4170. Is that fair to say?

[ggetz]

I'd like to confirm with @arobison—but if we have a sufficient workaround with orderIndependentTranslucency: false, and we have a plan to address the blending behavior as part of handling z-ordering and/or styling, I'm comfortable moving forward without a "fix" for this in the Sept 1 release.

[donmccurdy]

... are we looking at a manifestation of #4170. Is that fair to say?

I think that's fair, yes. A few options, not mutually exclusive:

• (a) Offer orderIndependentTranslucency: false as a workaround
  • Available already. It may not suit every use case but it's a helpful option.
• (b) Expose blendOption as an option on Cesium3DTileset or Cesium3DTileStyle
  • I'm personally more comfortable with (b) than (c). I worry that sudden changes going from alpha=0.99 to alpha=1.0 (e.g. during animation) will be unexpected for users, it's hard to infer user intent, and I suspect it might be safer and more predictable to let the user express their intended blending option for vector tiles. That said ... if there are long-standing conventions for how to handle transparency and OIT in CesiumJS, I'd rather defer to those conventions, aiming for "least surprise".
• (c) Automatically infer blendOption based on Cesium3DTileStyle evaluation
  • See above.
• (d) Attempt to improve OIT results
  • I assume this is very difficult, but haven't looked closely at it.
• (e) Move vector tiles to a separate pass, without OIT
  • No objection to this, but I don't feel like I understand the use cases enough to justify it yet.
• (f) Support BlendOption.OPAQUE_AND_TRANSPARENT for vector tiles
  • Honestly I don't 100% understand this option in CesiumJS yet; is it used to mitigate OIT complications like this one? Could be an option if so. Currently vectors use either the opaque or transparent pass, but not both.

In my opinion, it might be ideal to include EITHER (b), (c), or (f) in the Sept 1 release. But I don't think these are a hard requirement, with #4170 as a known issue and (a) available to work around it. I might lean toward (b) as the simplest and most predictable.