Create partial reference implementation for BENTLEY_materials_planar_fill (behind) by markschlosseratbentley · Pull Request #13178 · CesiumGS/cesium

markschlosseratbentley · 2026-02-02T15:38:15Z

Description

This PR adds support for the BENTLEY_materials_planar_fill glTF extension, enabling CAD-style planar polygon fill rendering with proper depth sorting and configurable fill behavior including background color masking and coplanar geometry ordering. Note: The wireframeFill property is currently a no-op as CesiumJS does not yet have a proper wireframe rendering mode. See this wireframe rendering mode draft PR for a possible way forward.

Issue number and link

Partially fixes #12890

Testing plan

Various unit tests have been added to CesiumJS related to this feature.
Otherwise, changes have been verified with the comprehensive test case added in the gltf-planar-fill-dev Sandcastle sample.
Test these changes using the planar fill Sandcastle sample deployed right here.

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

github-actions · 2026-02-02T15:38:40Z

Thank you for the pull request, @markschlosseratbentley!

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

danielzhong · 2026-03-18T05:05:13Z

Great work! I did a quick review of the glTF loading and the feature ID comparison logic. The approach of introducing a new pass and comparing feature IDs to determine what’s behind makes sense to me. I haven’t run it locally yet, but the overall idea and implementation look solid and follow a similar path to how edge visibility was handled.

However, While testing with some cases I generated from the tileset publisher encoding work (PR: https://github.com/iTwin/imodel-native-internal/pull/950), I noticed the results weren’t behaving as expected. The results still didn’t match the rendering in the iTwinJS PR (iTwin/itwinjs-core#8906). Note: I temporarily commented out the edge visibility code locally since support for “line string” hasn’t been merged yet.

For example, the “behind” flag in following test cases do not appear to be applied correctly:
PlanarFillBehind.zip

in iTwinJS:

But in the current branch in CesiumJS, both files appear as if the “behind” flag is not being read at all.

I have a question about the yellow color in this example. If both flags are enabled, my understanding is that it should either render as the black background or appear behind the other two colors. But it doesn’t seem to match either case here(it's rendering yellow and z fighting (meaning it's not behind anything)).

There’s also a purple test case with the same flags enabled compare with the yellow color test case I mentioned. The only difference is wireframe mode (which maybe shouldn’t affect the result), but the output looks different. The purple I highlighted isn’t visible—possibly rendering as black instead?

Am I misunderstanding how this is supposed to work?

Additionally, I’ve verified that the tileset publisher encoding behaves as expected in iTwinJS for planar fill. It might be a good idea to also use this renderer to validate the tileset publisher encoding, so we can confirm that both the tileset publisher and this implementation are working correctly. We can also add more test cases if needed.

markschlosseratbentley · 2026-03-18T12:00:52Z

For example, the “behind” flag in following test cases do not appear to be applied correctly

Investigating.

I have a question about the yellow color in this example. If both flags are enabled, my understanding is that it should either render as the black background or appear behind the other two colors. But it doesn’t seem to match either case here(it's rendering yellow and z fighting (meaning it's not behind anything)).

There’s also a purple test case with the same flags enabled compare with the yellow color test case I mentioned. The only difference is wireframe mode (which maybe shouldn’t affect the result), but the output looks different. The purple I highlighted isn’t visible—possibly rendering as black instead?

Am I misunderstanding how this is supposed to work?

Some of the colors in the test case are a fair bit similar - sorry about that. The "yellow" color you point out is actually slightly yellow with a tint of green and this is what it corresponds to, which appears to work as expected to me:

Regarding the purple test case: you are correct, the deep purple test case is indeed not visible. Since it has bgFill set to true, it will render as the background color (black). This is expected.

Additionally, I’ve verified that the tileset publisher encoding behaves as expected in iTwinJS for planar fill. It might be a good idea to also use this renderer to validate the tileset publisher encoding, so we can confirm that both the tileset publisher and this implementation are working correctly. We can also add more test cases if needed.

100% agree, and this is on my list but doesn't need to block PR review. I want to get a good "infrastructure" example converted through the tiler using this extension (and your tiler branch for planar fill). The one I have included with this PR is good for testing.

mzschwartz5

Hey @markschlosseratbentley, looking good to me. Most of my comments are code style nits or questions. Functionally, seems alright. I have more reading and testing to do but shipping this round of comments in the mean time.

mzschwartz5 · 2026-07-08T18:05:52Z

+        defined(primitive.featureIds) && primitive.featureIds.length > 0;
+
+      if (hasFeatureIds) {
+        const featureIdMember = primitive.featureIds[0].positionalLabel;


Is there something in the planar fill spec that guarantees a primitive has one (and only one) feature ID?

The spec does not guarantee a single feature ID set. The spec intentionally leaves "belonging to the same logical object" implementation-defined (for Bentley/iTwin it means "originating from the same element").

This implementation defines it as the primitive's first feature ID set, which holds for Bentley-produced tiles; primitives with no feature IDs simply don't participate in the behind test. I've now documented this assumption explicitly in the new processPlanarFill() docs and at the featureIds[0] access.

mzschwartz5 · 2026-07-08T18:07:01Z

+      const hasFeatureIds =
+        defined(primitive.featureIds) && primitive.featureIds.length > 0;
+
+      if (hasFeatureIds) {
+        const featureIdMember = primitive.featureIds[0].positionalLabel;
+        shaderBuilder.addDefine(
+          "HAS_PLANAR_FILL_BEHIND",
+          undefined,
+          ShaderDestination.FRAGMENT,
+        );
+        shaderBuilder.addDefine(
+          "PLANAR_FILL_FEATURE_ID",
+          featureIdMember,
+          ShaderDestination.FRAGMENT,
+        );


Since this logic is needed in both branches, it can be hoisted above both.

mzschwartz5 · 2026-07-08T18:10:12Z

+        // Mark this primitive for the pre-pass derived command.
+        renderResources.planarFillIdPass = true;


Not sure I understand why only this primitives not marked "hasBehind" get this flag set to true. Your comment above implies to me that both behind and non-behind planar-fill geometry participate in the feature-ID pre-pass.

Or is it only non-behind geometry that populates the feature ID texture? (I suppose that could make sense... "behind" geometry only cares about / needs to check "non-behind" geometry.)

Non-behind fills write the ID texture in the pre-pass; behind fills only read it. I've reworded the comments to say READ/WRITE explicitly.

mzschwartz5 · 2026-07-08T18:12:01Z

+        uniformMap.u_isPlanarFillIdPass = function () {
+          return false;
+        };


A comment here that this is overridden by the derived command could be helpful

Added a comment noting the default returns false for the main command and that derivePlanarFillIdCommand overrides it to return true.

mzschwartz5 · 2026-07-08T20:07:07Z

+  const planarFill = new PlanarFill();
+  planarFill.wireframeFill = wireframeFill;
+  planarFill.backgroundFill = backgroundFill;
+  planarFill.behind = behind;


Any reason for not just giving PlanarFill a constructor that takes and deconstructs a PlanarFillInfo object?

side note- could we make a jsdoc typedef for the input object here?

Yep, that's a good suggestion and cleans it up a lot. Done.

PlanarFill now has a constructor that takes and destructures the extension JSON and has @param docs.

mzschwartz5 · 2026-07-08T20:15:15Z

+ * and non-behind fills — but NOT behind other objects.
+ *
+ * Layout:
+ *   Color attachment 0 – RGBA: R = encoded feature ID (float), GBA reserved.


What are GBA reserved for? Could we use not just use an attachment with a single channel (R) to save memory?

GBA was a conceptual reservation during development. It ended up we didn't need them in this implementation. Good callout. I moved this to a single-channel R attachment. All seems to work correctly still.

mzschwartz5 · 2026-07-08T20:18:55Z

+  // indicates we can render to float textures, not just create them.
+  // Fall back to UNSIGNED_BYTE if neither is supported.
+  let pixelDatatype;
+  if (context.colorBufferFloat) {


I wonder if we really have to check for support here. I think we decided recently that new features don't need to support webgl1, and in webgl2 this extension is established in all browsers we support.

Also- why not use an UNSIGNED_INT data type? Does it have to do with the fact that the same shader doubles for both feature IDs and the fill?

Thanks for the pointer about not needing webgl1 support.

I went ahead and dropped the HALF_FLOAT branch. I did keep a minimal context.colorBufferFloat ? FLOAT : UNSIGNED_BYTE guard, because tests could possibly not advertise the extension.

Open to changing this further.

RE: UNSIGNED_INT: integer output would require an integer output declaration. Due to shader program sharing, we keep the vec4 output here (float is fine range for representing IDs).

mzschwartz5 · 2026-07-08T20:35:57Z

+// ──────────────────────────────────────────────────────────────────────
+// BENTLEY_materials_planar_fill constants
+// ──────────────────────────────────────────────────────────────────────
+// Depth pull factor (0.05% toward camera) for all planar fills.


~~Did you mean to write 5% instead of 0.05% (and same for 2%)?~~

Also, I think this comment is a little misleading. I think it needs to call out that the depth pull/push occur in log space, after czm_writeLogDepth. This 5% pull is 5% in log space, which is a variable amount in eye space depending on the fragment's distance from the camera. (Which may be the intended effect)

The percentages are actually correct as written: 1 − 0.9995 = 0.0005 = 0.05%, and 1.0002 − 1 = 0.02%. But your second point about log space is fair. It's intended behavior. The comment block now spells all of this out.

mzschwartz5 · 2026-07-08T20:47:56Z

+    #ifdef HAS_PLANAR_FILL_BEHIND
+    {
+        vec2 screenCoord = gl_FragCoord.xy / czm_viewport.zw;
+        float storedEncoded = texture(czm_planarFillIdTexture, screenCoord).r;
+        float storedFeatureId = storedEncoded - FEATURE_ID_OFFSET;
+        float myFeatureId = float(featureIds.PLANAR_FILL_FEATURE_ID);
+
+        // storedFeatureId < 0 means "no planar fill at this pixel".
+        if (storedFeatureId >= 0.0 && abs(storedFeatureId - myFeatureId) < FEATURE_ID_TOLERANCE) {
+            // Proportional push: multiply by >1 to move away from camera.
+            // Net effect: PLANAR_DEPTH_PULL * BEHIND_DEPTH_PUSH ≈ 0.9997,
+            // still in front of non-planar but behind same-feature non-behind fills.
+            gl_FragDepth *= BEHIND_DEPTH_PUSH;
+        }
+    }


I need to think about this more... generally speaking, I've encountered numerous issues (many of which in my work with billboards) when trying to fudge depth values. It's very prone to sneaky edge cases.

With billboards, there were some issues I never solved and ultimately concluded a more robust solution would involve a separate render pass entirely...

Fair concern.

In the end, it's the same family of technique as the u_polygonOffset built into czm_writeLogDepth. Also, a similar proportional depth tolerance is employed in the edge visibility system. So there is precedent, which I was leaning on.

Also worth noting: the spec's "planar renders in front of non-planar at the same surface" semantics require some depth override regardless; a separate pass would still need the feature-ID comparison and a bias or depth-test trick inside it, so it isolates the problem more than it removes it (unless we sort things....)

That said, if some blocker artifact turns up, we could eventually move this into a dedicated pass and try to figure something out. Most of the scaffolding here could carry over.

markschlosseratbentley · 2026-07-09T11:27:30Z

Thanks @mzschwartz5 - I'll be going through your feedback.

markschlosseratbentley added 8 commits January 27, 2026 13:45

first cut

db3989e

Merge branch 'main' into BENTLEY_materials_planar_fill

b3b608f

merge

3caa255

merge

b54e4dd

change test

6d76a79

gltf file

187cf03

declare / describe planar fill property

0478d5b

first cut of backgroundFill, including sandcastle sample

82f2a98

This was referenced Feb 5, 2026

Create CAD Wireframe Mode in CesiumJS #13191

Closed

Add EdgeDisplayMode enum for controlling edge rendering #13192

Merged

document no-op for wireframeFill

a49d995

markschlosseratbentley changed the title ~~Create reference implementation for BENTLEY_materials_planar_fill~~ Create reference implementation for BENTLEY_materials_planar_fill (wireframeFill) Mar 5, 2026

markschlosseratbentley changed the title ~~Create reference implementation for BENTLEY_materials_planar_fill (wireframeFill)~~ Create partial reference implementation for BENTLEY_materials_planar_fill (backgroundFill) Mar 5, 2026

markschlosseratbentley changed the title ~~Create partial reference implementation for BENTLEY_materials_planar_fill (backgroundFill)~~ Create partial reference implementation for BENTLEY_materials_planar_fill (behind) Mar 5, 2026

markschlosseratbentley mentioned this pull request Mar 5, 2026

Create partial reference implementation for BENTLEY_materials_planar_fill (backgroundFill) #13266

Closed

9 tasks

markschlosseratbentley added 3 commits March 5, 2026 10:35

behind cut 1 - needs refining

915bc1d

fix behind

c0db667

behind and depth ordering logic

1c72b33

markschlosseratbentley requested a review from danielzhong March 12, 2026 19:18

markschlosseratbentley added 7 commits March 12, 2026 15:47

make the offset more robust. remove polygon offset.

dbbf87f

prioritize float buffer, add macros for offsets

9131630

fix test

877922b

lint

7b3b908

Merge branch 'main' into BENTLEY_materials_planar_fill

03d0b8a

CHANGES.md

7b1e097

tests

35c944b

markschlosseratbentley mentioned this pull request Mar 17, 2026

SkyBox.show = false is ignored (regression since 1.139) #13311

Closed

markschlosseratbentley added 2 commits March 17, 2026 10:31

workaround bug in hiding skybox

94163e8

fix tests for ci

0d6b42c

merge

917616b

markschlosseratbentley marked this pull request as ready for review March 17, 2026 15:04

Merge branch 'main' into BENTLEY_materials_planar_fill

c04de89

markschlosseratbentley mentioned this pull request Mar 18, 2026

Fix regression where SkyBox.show = false is ignored #13315

Merged

6 tasks

markschlosseratbentley added 3 commits March 31, 2026 10:46

add SketchOnSurface example

c1f14da

Merge branch 'main' into BENTLEY_materials_planar_fill

cc2b059

edge display on for planar fill test

5199976

j9liu mentioned this pull request Jun 29, 2026

Support BENTLEY_materials_planar_fill CesiumGS/cesium-unreal#1865

Open

ggetz assigned mzschwartz5 Jul 7, 2026

mzschwartz5 requested changes Jul 8, 2026

View reviewed changes

markschlosseratbentley added 2 commits July 10, 2026 12:25

Respond to planar fill PR review with some changes.

2038f6f

move some processPlanarFill docs to function header

be2ef0b

markschlosseratbentley mentioned this pull request Jul 10, 2026

Implement wireframeFill from BENTLEY_materials_planar_fill #13620

Open

markschlosseratbentley added 5 commits July 10, 2026 15:42

change planar fill docs to link to wireframe mode GH issue

53433db

planarFillIdPass - boolean optimizations

324cfbd

Merge branch 'main' into BENTLEY_materials_planar_fill

8d579da

merge

3924722

merge

78166a3

		// Mark this primitive for the pre-pass derived command.
		renderResources.planarFillIdPass = true;

Uh oh!

Conversation

markschlosseratbentley commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue number and link

Testing plan

Author checklist

Uh oh!

github-actions Bot commented Feb 2, 2026

Uh oh!

danielzhong commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markschlosseratbentley commented Mar 18, 2026

Uh oh!

mzschwartz5 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markschlosseratbentley commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

markschlosseratbentley commented Feb 2, 2026 •

edited

Loading

danielzhong commented Mar 18, 2026 •

edited

Loading

mzschwartz5 Jul 8, 2026 •

edited

Loading