Dropping support for glTF 1.0

Hi everyone,

We recently overhauled the model code and will no longer officially support glTF 1.0 in CesiumJS 1.97 and above. glTF 1.0 support was deprecated in CesiumJS 1.94. Since this is a large change I wanted to reach out to the community to see if anyone is using glTF 1.0 and provide suggestions for upgrading.

For more background - glTF 1.0 allows models to contain embedded shaders. While this provides a lot of flexibility it’s complicated to support in the new model architecture. Since glTF 2.0 has much wider adoption we felt that the time was right to remove support for glTF 1.0.

We’ll still do a best effort runtime conversion from glTF 1.0 to 2.0 but any models that rely on specialized shader code for lighting, billboard effects, or attribute compression may no longer work.

Let us know if this impacts you. If you have glTF 1.0 assets or 3D Tiles that reference glTF 1.0 you can try out the latest code in main and see if they continue to work or not.

For more details about the glTF 1.0 to 2.0 upgrade step, see Limited support for glTF 1.0 in the new model implementation by lilleyse · Pull Request #10648 · CesiumGS/cesium · GitHub


This just came to my attention. GeoFS is using almost exclusively GLTF 1 models and relies on custom shaders precisely “for lighting and billboard effects” and other tricks. There is also a large library of user contributed models that are mostly in the GLTF 1 format. I will investigate the possibility to run GLTF 2 models with custom shaders (I am not too keen on using generic looking PBR material on which we have very little control) but frankly, this is all a rather difficult news to me.

@Xavier_Tassin Thanks for the feedback. Definitely give custom shaders a try. I’m sure @ptrgags would be happy to help if there are specific effects you’re trying to achieve.

The Custom Shader Guide is a good starting point. There are also a few sandcastles to explore.

Thanks @sean_lilley for the pointers.

Can we expect KHR_technique_webgl extension to be implemented once ratified by the Khronos group?

I don’t expect KHR_techniques_webgl to be ratified since it was moved to an archived section. It would be difficult to support in the same way that glTF 1.0 is.

I am starting to experiment with customShaders but I have to admit I find this rather restrictive compared to what was possible with GLTF 1. Correct me if I am wrong but it appears only one shader can be assigned to a GLTF model. I used to have several shaders per model, especially when mixing opaque/translucent materials: airplane fuselage and windshield. What would you suggest in this situation?

CustomShaderGuide does not give any indication on how I could reuse textures declared in the GLB file and loaded at the same time as the model. If this is not possible, then a new http request to the server is required to load the same textures (even though they may be cached)

Correct me if I am wrong but it appears only one shader can be assigned to a GLTF model.

That’s right. And a fair point.

CustomShaderGuide does not give any indication on how I could reuse textures declared in the GLB file and loaded at the same time as the model.

This could be solved if custom shaders worked with ResourceCache: #10718. Or if the material was accessible to custom shaders.

Basically I see two paths forward here:

  • Keep adding functionality to custom shaders
  • Add a special glTF 1.0 pipeline stage that runs isolated from other stages

@ptrgags How much work would a glTF 1.0 stage be?

In general, I’m all in favor of pushing forward: adding feature to the glTF 2.0 (and custom shaders) implementation is certainly the way to go.

However, I also like to see backward compatibility maintained: is it really impossible to keep the glTF 1.0 implementation as a legacy feature (accessible via a renamed API just like ModelExperimental lived side-by-side with the current model API).

It feels like not much notice was given to make the move and, speaking for myself, this represent major re-work and many problems ahead.

We’ve hit an issue with our migration here: CustomShader via CZML model?

Thanks for pointing that out @coops-propeller

Our team is going to discuss what it would take to maintain backwards compatibility with glTF 1.0 and KHR_techniques_webgl.

1 Like

Hi all, sorry for the delay. It took a while to gather my thoughts on this.

I wrote up an Issue in CesiumJS that describes some of the difficulties of supporting glTF 1.0 techniques/KHR_techniques_webgl, as well as a few possible approaches to implementing it. That issue has a ton of detail, so the TL;DR is this:

  • Each option has tradeoffs in terms of feature compatibility, amount of shader processing required, etc.
  • Option B seems the most plausible, though non-typical attributes (e.g. vec2 oct-encoded normals) may pose difficulties

@Xavier_Tassin and @coops-propeller, one question I have for you is what features do you use in tandem with glTF techniques?

  • Is all the shading done in the technique itself?
  • Or do you apply other CesiumJS features on top of it? (e.g. applying a highlight color, a Cesium3DTileStyle, etc.)

Some Model features will be easier to integrate than others, so I’d like to get an idea of what people use in practice.

@ptrgags, I usually just replace the glTF shaders with my own. This usually involves multiple materials/techniques with mixed opacity and texture as I already mentioned it. No other features are applied.

We use a mix of dynamic (ie server side generated on request) and static GLTFs, either within 3D tilesets or as models within a CZML convenience wrapper alongside some non-model geo. Often for data visualisation we’ll use a per-vertex colour and opacity, and non-PBR custom shader.

As an observation it seems the Cesium API might be getting a bit fragmented (no pun intended) for custom shading, e.g. with MaterialAppearance, Material/Fabric, CustomShader providing similar but different APIs and capabilities. I wonder if it is possible to consolidate any of these approaches?

Has any decision been made on this already?

Backwards compatibility for glTF 1.0 models will likely not be a priority for the team in the near future, though if you have the bandwidth to make a contribution, we’d be happy to discuss and review a PR.

1 Like

Hi @Gabby_Getz,

This is noted and I am now fully moving toward GLTF2.0

However, the most difficult limitation to deal with right now is the fact that custom shaders allow only one material to be applied.

Is there a plan to improve this in the short term or is it best to work around this limitation for now?

Thanks you.

Hi @Xavier_Tassin,

We have no immediate plans to extend custom shaders to multiple materials.

Though we would be happy to take a PR for this, or recommend a workaround. @ptrgags Would likely be the best to advise on the approach.

Would you be able to tell us a bit about the effect you are looking to achieve with multiple materials? Perhaps it’s still possible to implement with a custom shader.

I used to render GLTF1.0 aircraft models with a minimum of two materials:

  • for the fuselage: opaque with my own sort of PBR shading (albedo, normal, specular and environment mapping)
  • for windows and windscreen: translucent with environment mapping and specular lighting

Working with GLTF2.0, I see two possible workarounds:

  • export models with multiple materials. But if I need to tune anything in the shading (say, I want my aircraft a bit more shinny), I need to re-export all my models. This also implies that I am stuck with the native implementation of PBR.
  • use an opacity map (or branching in the fragment shader). But that means everything, opaque or translucent, will have to render in the translucent pass. I am not sure if this would be a problem. This also implies that I rework all textures files and UVs for my models.