CesiumGS / CesiumGS/cesium

3D Tiles Styles and Custom Shaders should not crash on undefined properties

Open
#13,199 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

category - 3d tiles type - enhancement
Dominant language
JavaScript
Stars
15.8k
Forks
3.9k
Avg merge
4d 6h
Merged PRs (30d)
34

Description

Feature

A given 3D tileset can contain multiple models. Each model may have different metadata - and reference different metadata schema. Yet a tileset, loaded into CesiumJS, can only have a single Cesium3DTileStyle, and a single CustomShader. This makes it difficult to style or apply custom shaders using properties that exist on some models in the tileset but not others. In both cases (styles and shaders), use of a property that's not defined on every model will crash CesiumJS.

My proposal is that undefined properties should not crash styles and shaders. Instead, they should simply be skipped over. I'm not sure yet how that would work for styles (maybe it's easy), but I've looked into the CustomShaderPipelineStage, and I think we should expose the concept of preprocessor macros to the end user. Something like:

const myCustomShader = new Cesium.CustomShader({
  vertexShaderText: `
    void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput)
    {
#if HAS_PROPERTY(myDisplacementProperty)
        vsOutput.positionMC += vsInput.attributes.normalMC * vsInput.metadata.myDisplacementProperty;
#endif
    }
  `,
});

If implemented properly, I think this approach could open the door for other user-accessible custom shader preprocessors in the future, should we need them.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at CustomShaderPipelineStage and trace the corresponding 3D Tiles style path; these are the only entry points named, and no files or tests are specified. Establish how properties missing from some models should behave, then verify that both styles and custom shaders skip undefined properties without crashing.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
computer-graphics
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.